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STATIC REGIONS 



INTRODUCTION 

Logical address space in a task is composed of regions. 
There are three basic types of regions, task regions, static 
regions, and dynamic regions. Task regions, into which tasks are 
loaded, are created using information set up by the Task Builder. 
Static and dynamic regions are generally used to share code or 
data among several tasks. Static regions are created using the 
Task Builder; dynamic regions are created during task execution, 
using executive directives. 

This module discusses static regions. You can use these 
static regions to: 

• Create memory areas containing code which is shared among 
tasks 

• Create memory-resident data areas which can be used for 
communication between tasks or successive invocations of 
the same task 

• Communicate directly with a peripheral device through the 
I/O page. 



OBJECTIVES 

1. To create and use a resident common region 

2. To create and use a resident library 

3. To determine whether a position independent or an absolute 
shared region should be used in a given situation 

4. To create and use a device common. 



RESOURCE 

• RSX-11M/M-PLUS Task Builder Manual, Chapter 5 
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TYPES OF STATIC REGIONS 

Static regions, also called shared regions, are areas of 
memory which are shared among tasks. They allow tasks to share 
data or code with very little overhead. Unlike send and receive 
directives, no executive directives are needed, and the area's 
size is limited only by virtual address and possibly physical 
memory limitations. The virtual addressing limit must be met for 
both the region itself and any tasks which use the region. For a 
task which uses the region, the total applies to all regions used 
plus the task's code. 

Static regions offer very quick access, since the area is 

loaded before the tasks which use it are run. Once loaded, it is 

available directly in memory. Therefore, it offers much faster 
access than disk-resident data. 

Table 7-1 summarizes the types of shared regions available on 
an RSX-11M system. A resident common contains data. The data can 
be accessed by several different tasks, each with read only access 
or with read/write access. 

A resident library contains reentrant subroutines, which can 
be called by several different tasks. A single copy of each 
subroutine can be shared, thus reducing the total memory 
requirements of the tasks. The term resident is used because the 
shared region is task-built, installed, and loaded into memory 
separately from the tasks which access it. 

A third type of shared region is a device common, a special 
type of resident common. It occupies physical addresses on the 
I/O page, which correspond to I/O device registers instead of 
physical memory. Therefore, this kind of common allows a task to 
reference an I/O device directly. Unlike other resident commons, 
a device common has no true contents because it has no physical 
memory associated with it. 
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Table 7-1 Types of Static Regions Available on RSX-11M 



Type of Region 
Resident Common 



Resident Library 



Device Common 



Contents 

Data accessed 
by two or more 
tasks 



Reentrant routines, 
used by two or more 
tasks 

No true "contents" 

Region is a range 

of physical addresses 

within I/O page 



Advantages 

Serves as com- 
munications link 

Serves as memory- 
resident data base 



One copy 
routines 
memor y 



of common 
shared in 



Nonpr ivileged task 
can directly access 
an I/O device with- 
out being mapped to 
the Executive 
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MEMORY ALLOCATION 

Memory is allocated independently to the shared region and to 
the individual tasks which use it. We will call the tasks which 
use the region referencing tasks. On an RSX-11M system, the 
shared region must reside in a dedicated common type partition. 
The name of the partition must be the same as the name of the 
region. The partition can be created at SYSGEN time or later by 
the system manager or a privileged user. Once the region is 
installed and loaded into the partition, it cannot be 
checkpointed . 



MAPPING 

Shared regions can be written and task-built as either 
position independent regions or as absolute regions. On a mapped 
system, position independent regions can be placed anywhere in a 
referencing task's virtual address space. This means that the 
virtual addresses used to map to the region can correspond to any 
available APR. 

Figure 7-1 shows a position independent region, POSIND, and 
three referencing tasks. " The region is loaded into memory into 
the partition POSIND; the partition name must be the same as the 
name of the region. Recall that a virtual address window for 
mapping must begin with a base address for an APR on a 4K word 
boundary. Because the region is 5K words in length and each APR 
can only map at most 4K words, two APRs are needed to map the 
reg ion . 

Task A maps the shared region using APRs 6 and 7, starting at 
virtual address 140000(8). It could in fact use APRs 5 and 6, 
beginning at virtual address 120000(8) or APRS 4 and 5, beginning 
at virtual address 100000(8). 

Task B maps the shared region at the first available APR 

above the task code, using APRs 2 and 3, beginning at virtual 

address 40000 (8). It could use APRs 3 and 4, 4 and 5, 5 and 6, or 
6 and 7 as well. 
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Task C maps the shared region using APRS 6 and 7, starting 
with virtual address 140000(8). There is no other possible way 
for Task C to map the shared region because APR 6 is the first 
available APR. 

When you task-build a referencing task, you can specify which 
APR to use in mapping the region. If you do not specify an APR, 
the Task Builder selects the highest set of available APRS. When 
task A and task C were built, the user either did not specify an 
APR, or specified APR 6. When task B was built, the user 
specified APR 2. 
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Figure 7-1 Tasks Using a Position Independent Shared Region 
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An absolute shared region has its virtual addresses fixed 
when it is task-built. All tasks which reference it must use 
those virtual addresses, and the corresponding APRs , to map to the 
region. Figure 7-2 shows another region ABSOLU and three 
referencing tasks, A, B and C. The shared region ABSOLU was built 
to use virtual addresses 120000 (8 ) -1 47777 (8 ) (6K words) with APRs 
5 and 6. All referencing tasks must map to the region using these 
APRs. Therefore, task A and task B can both map to the region, 
since APRs 5 and 6 are available. Task C, on the other hand, 
cannot reference ABSOLU, since APR 5 is already used by its task 
code . 

You may think that there is no reason to ever limit yourself 
by making a region absolute. However, there are code restrictions 
for position independent regions due to the fact that a shared 
region is task-built separately from any of its referencing tasks. 

When the region is task-built, all code within it is set. 
The code has to be written using special position independent 
coding techniques to allow it to be placed at possibly different 
virtual addresses in the various referencing tasks. This is only 
a problem for data if the data is not position independent; for 
example, a jump table. 

The starting virtual address of each routine, defined by its 
label, is assigned when the referencing task is task-built. This 
address may vary depending on which base APR is used to map the 
region. The address of a given routine may vary from one 
referencing task to another. But the address placed in the table 
itself was already fixed when the region was task-built, and does 
not change for each referencing task. Further, that address may 
not match any of the addresses assigned in referencing tasks. For 
example, consider the following jump table and routines W, X, and 
Y: 

JMPTAB: .WORD W 
.WORD X 
.WORD Y 

W: 



X: 



Y: 



296 



STATIC REGIONS 



160000 
140000 
120000 
100000 
60000 
40000 
20000 




160000 
140000 
120000 
100000 
60000 
40000 
20000 




APR7 
APR6 
APR5 
APR4 
APR3 
APR2 
APR1 
APRO 



APR7 
APR6 
APR5 
APR4 
APR3 
APR2 
APR1 
APRO 



VIRTUAL 
MEMORY 

TASK A 



m 

Z^UNUSED/ 



ABSOLU 

(6K WORDS) 

777777777777777777777, 
^UNUSEDp 



TASK 
WINDOW 

(16K WORDS) 



TASK B 



TASK C 



I 



■ 


w///////M///m////// / 

W////m/////////////////< 


■/ 




ABSOLU 

(6K WORDS) 






PIIIP 






TASK 
WINDOW 

(8K WORDS) 





/ 



160000 


APR7 






140000 


APR6 






120000 


APR5 






100000 


APR4 




TASK 


60000 


APR3 




WINDOW 


40000 


APR2 




(24K WORDS) 




20000 


APR1 









APRO 







CAN'T 

REFERENCE 

ABSOLU 



PHYSICAL 
MEMORY 



ABSOLU 

(ABSOLUTE REGION) 



TASK 
REGION 

(TASK A) 



TASK 

REGION 

(TASK B) 



Figure 7-2 Tasks Using an Absolute Shared Region 



297 



STATIC REGIONS 



The addresses resulting from the .WORD directives are fixed 
when the region is task-built; e.g., at W = 1500 (8), X = 1540 (B), 
and Y = 1626(8). If the referencing task places the actual 
addresses W, X and Y at those virtual addresses, everything will 
work fine. But if it starts mapping at APR 4 (virtual address 
120000), the labels themselves will be assigned addresses 
120000 (8) + 1500 (8) = 121500 (8), 120000 (8) + 1540 (8) = 121540 (8), 
and 120000 (8) + 1626 (8) = 121626 (8). 

However, the values in the table are already set at 1500 (8), 
1540(8), and 1626(8), and they no longer address the correct 
locations. A jump or call by way of the table to routine W will 
result in a transfer to location 1500(8) in the referencing task, 
and definitely not to routine W. To avoid this problem, jump 
tables should be included in the referencing task code instead of 
in the shared region. 

Instructions in shared regions are even trickier to program. 
All references which are relative to the current PC, for example, 
eight bytes from here, work fine. But a reference to an actual 
virtual address, for example, virtual address 4260(8) or @#A, only 
works if 4260(8) or A remains set at that virtual address. For a 
discussion of position independent code and how to write it, see 
Appendix H of the IAS/RSX-11 MACRO-11 Reference Manual . 

All of this means that in general , the decision about whether 
to create a position independent or an absolute shared region is 
based on the code restrictions, rather than the flexibility. In 
general, resident commons, containing data, are created position 
independent; and resident libraries, containing code, are created 
absolute. 

Figure 7-3 shows the program development process for creating 
a shared region and a referencing task. Specific steps for each 
process are discussed later in this module. Assemble and 
task-build the shared region separate from the referencing task, 
and before task-building the referencing task. 

Since it is not an executable task, certain task-build 
switches are used to create a task image with no header and no 
stack. An additional file, called a symbol definition file, is 
also created at task-build time. This file contains information 
about the symbols defined in the region, which the Task Builder 
will use when it builds the referencing task to set up linkage to 
the region. 
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After task-building the shared region, task-build the 
referencing task. It can be written and assembled earlier, if 
desired. The name of the region is specified to the Task Builder 
so that it can access the symbol definition file and set up the 
linkage to the shared region. The shared region must be installed 
(causing it to be loaded into memory as well) before any 
referencing task is run. 



REFERENCES TO A SHARED REGION 

The following kinds of references are made to a shared region 
by a referencing task: 

• The task retrieves data from, or stores data in, a 
resident common. 

• The task calls or jumps to a routine in a resident 
1 ibrar y. 
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Figure 7-3 Program Development for Shared Regions 
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Techniques of Referencing 

When you write the code for the shared region and the 

referencing task, you must pick a technique to resolve the 

references to the shared region. Some of the techniques are the 

same as the ones we used in Chapter 6 for referencing data in the 
root from an overlay segment. 

Using Overlaid Psects (Data Only) 

This technique is similar to the one for overlays. An 
example appears below. This time the Overlaid (OVR) Psect is 
defined in the shared region, then the same Psect is specified in 
the referencing tasks. The Task Builder, as usual, combines the 
different occurrences of each psect. Because the shared region is 
built first, the Psect MYDATA is placed there. Later, when the 
referencing task is built, the new occurrence of MYDATA is 
combined with the one in the shared region. The OVR attribute 
tells the Task Builder to start the allocation at the same 
location as the allocation already there, causing the addresses to 
be overlaid. This, in effect, just sets up the addressing so that 
M references the first word of the region, the 3. 

Shared region: 

• PSECT MYDATA D,GBL, OVR ; Defaults: RE L , RW 
.WORD 3., 4., 5. 

• END 



Referencing task: 

.PSECT MYDATA D , GB L , OVR ; PSECT in shared 

; region 

M=. ; Addr of start of region 

.PSECT ; Back to blank Psect 



START: CMP M,#5 ; Check value 

BGT FIFTY ; Branch if greater 



301 



STATIC REGIONS 



Using Global Symbols (Data or Subroutines) 

This technique is also the same as the one used in overlays. 
An example for data and for a subroutine appear below. In both 
cases, the label or labels are defined as global symbols. The 
referencing task uses the same global symbols to access the data 
or to call the subroutine. The possibly needed Psect name will be 
discussed later in the module. 



For Data 



Shared region: 

; Possibly needed psect name 
.PSECT ZZZ 

M : : .WORD 3., 4. ; Define data and symbols 

N : : .WORD 5. 

. END 



Referencing task: 

CMP M,#5 
BGT FIFTY 



; Check value 

; Branch if greater 



For Subroutine Names 

Shared region: 

; Subroutine 
AADD: : 

RETURN ; Return 



Referencing task: 
; Set up arguments 

CALL AADD ; Call subroutine 
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Using Virtual Addresses (Data Only) 

This technique is not available with overlays. If the shared 
region is built absolute, the starting virtual address of the 
region is fixed when the region is task-built. In the example 
below, it is assumed that the region is task-built absolute to 
begin at virtual address 160000(8). The referencing task can 
access the data by using the actual virtual address where the data 
is mapped. 

If the region is built position independent, it can be mapped 
at a specific base virtual address (or base APR) by specifying a 
base APR in the task-build command for the referencing task. In 
this example, specifying APR 7 would set the base virtual address 
for the region at 160000(8). 

Shared region: 

; Possibly needed psect name 
.PSECT ZZZ 
.WORD 3. ,4. ,5. 
. END 



Referencing task: 

; Shared region must be task-built either: 

; absolute starting at V.A. 160000 

; position independent and referencing task is 

; task-built to force region to start at 

V.A. 160000 

M = 160000 ; Addr of start of region 

CMP M,#5 ; Check value 

BGT FIFTY ; Branch if greater 
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Table 7-2 summarizes the techniques for referencing a shared 
region. When you task-build the shared region, you can specify 
whether or not you want the Psect names placed in the symbol 
definition file (.STB file) . They must be there if you use the 
technique of overlaid Psects to reference the region. Use the 
/SHAREABLE: COMMON qualifier (/CO in MCR) to include the Psect 
names . 

If global symbols or virtual addresses are used, it is best 
to exclude the psect names in the .STB file. Use the 
/SHAREABLE: LIBRARY qualifier (/LI in MCR) to exclude Psect names. 
This avoids possible task-build errors due to psect conflicts. 

If psect names are kept in the .STB file, each Psect defined 
in the region, including the default blank (. BLK.) Psect is 
there. The Task Builder tries to collect allocations together if 
a matching Psect name appears in the referencing task. However, 
it can't add to the allocation in the region, since the region is 
already built. Therefore, if the Psect results in additional 
allocation to the Psect (always true if the Psect has the 
concatenate (CON) attribute) , then a task-build error "LOAD 
ADDRESS OUT OF BOUNDS" results. This is because the new 
allocation can't be added to the already built shared region. 

Therefore, if psect names are placed in the .STB file, the 
Psect names in the referencing task must not match any in the 
shared region, including the default blank psect. Avoiding this 
is especially difficult if the shared region is a system resident 
library like FCSRES or FORRES, which was written by DIGITAL. In 
this case, you may not know what psect names were used in the 
original source code. 

As a general rule, place Psect names in the .STB file only if 
you use overlaid Psects to reference the region. Table 7-3 shows 
the interaction of three task-builder switches or qualifiers. 
They are: /CODE:PIC, for position independent or not; 
/SHAREABLE: COMMON, for placing Psect names in the .STB file; and 
/SHAREABLE : LIBRARY, for not placing psect names in the .STB file. 

The name COMMON is used for keeping psect names because 
overlaid psects can only be used for data references, therefore 
they are generally used in resident commons. The name LIBRARY is 
used for not keeping psect names because global symbols are 
generally used to reference subroutines in a resident library. In 
fact, if a resident common is referenced using global symbols or 
virtual addresses, it is also built /SHAREABLE: LIBRARY to avoid 
Psect conflicts. 
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Table 7-2 

Technique 

Overlaid 
Psec ts* 

MACRO-11 



Global 
symbols** 

MACRO-11 



Vi rtual 
addresses** 

MACRO-11 



Techniques of Referencing a Shared Region 
Shared Region Referencing Task 



Define offsets 
within Psect 

Subroutines or data 



Labels defined 
as global symbols 



Data only 



Use offsets within 
any psect 



Use same overlaid 
psect 



Data - use global 
symbol 

Subroutine - CALL or 
use JSR to global 
symbol 



Use same offsets 
from a base VA 

If shared region 
PI, specify APR 
for that base VA 

If shared region 
absolute, use same 
base VA 



* Must keep Psect names in .STB file 
** Possible psect conflicts 
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Table 7-3 Effect of /CODE: PIC, /SHAREABLE: COMMON, and 
/SHAREABLE: LIBRARY on a Shared Region's STB 



/ S HARE AB LE : C OMM ON 
(/CO) 



Position Independent 
/CODE: PIC (/PI)* 

Required for overlaid 
Psects or FORTRAN 
COMMONS 



Absolute by 
Default 

(/-PI, MCR only) 

Required for overlaid 
Psects or FORTRAN 
COMMONS 



/SHAREABLE : LIBRARY 
(/LI) 



Default 



Psect declarations 
are maintained as 
declared in the 
source code (default 
if /PI specified) 

Avoids Psect con- 
flicts 

A single Psect is 
declared name is 
same as first object 
file in TKB command 
Psect is relocat- 
able (REL) 

/SHAREABLE : COMMON 



Psect names saved but 
all are flagged as 
absolute (ABS) 



Avoids Psect conflicts 



A single Psect named 
. ABS. is used and 
is absolute 



/SHAREABLE : LIBRARY 



* Switches in parentheses are for MCR format (with the TKB 

IllllwIlllliH 
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PROCEDURE FOR CREATING SHARED REGIONS AND REFERENCING TASKS 



Creating a Resident Common or Resident Library 

1. Code your shared region. 

• Set up for an appropriate referencing technique. 

Choose either overlaid Psects, global symbols, or 
virtual addresses for a resident common. 

Use global symbols for a resident library. 

• Choose position independent or absolute. 

The decision is based mainly on the coding 
techniques used. 

If the code is position independent, build 
position independent (typical for resident 
common) . 

If the code is not position independent, build 
absolute (typical for resident library). 

• Resident common - reserve space, plus you may 
initialize locations. 

• Resident library - code must be reentrant. See the 
section on Reentrancy in Chapter 5 of the PDP-1 1 
Processor Handbook for more information a bo ut 
reentrant code. 

2. Assemble the shared region. 

3. If not already done, create the common type partition. 

• Name must be the same as the name of the region. 

• Best done when the system is SYSGENed. 

• Use the SET PARTITION (SET/MAIN in MCR) command to 
create a partition. 

• Use the SET NOPARTITION (SET/NOMAIN in MCR) command to 
eliminate a partition. 
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• Ex am pi e s : 

>SET PARTITION:MYCOM/BASE:7114/SIZE: 200- 
-> /COMMON 

Creates the common type partition MYCOM with base 
physical address 711400(8) and size 20000(8) bytes. 
No other partition may use this space at the same 
time. 

>SET NOPARTITION: MYCOM 
Eliminates the partition MYCOM. 

NOTE 

Before you create or eliminate any 
partitions on your system, check with 
your system manager to find out what 
area of memory you may use. 

4. Task-build the shared region. 

• Symbol definition file (.STB) required. 

• Build position independent or absolute (see Table 
7-3) . 

• Keep or do not keep psect names (see Table 7-3). 

• Use required switches and options (see Table 7-4) . 

5. Install the shared region in the common type partition 
before running any referencing task. 

• Not required before task-building the referencing 
tasks . 

• Use the INSTALL (INS in MCR) command to install the 
region. 

This command also loads the region into memory. 
This is unlike an executable task, which is 
usually loaded into memory only when it is 
activated. 
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• There is no command to remove a region. It is removed 
by either installing another region or eliminating the 
partition. 

The required switches and options in Table 7-4 are needed for 
different reasons. No header or stack is needed because this is 
not an executable task. The referencing tasks each have their own 
header and stack. The symbol table definition file is needed to 
allow the Task Builder to link referencing tasks to the region. 
The partition name specifies the partition into which the region 
will be loaded. 

For an absolute region you must specify a base address. If 
you specify a nonzero length, the specified value is used as a 
maximum length. A task-builder error results if the length of the 
region is longer than the length specified. If you specify a 
length of zero, the region is set up with the size needed for the 
code, as long as it doesn't exceed the 32K word virtual addressing 
1 imit . 



Table 7-4 Required Switches and Options for Building 

a Shared Region 



Swi tch/Option 
in DC L (MCR) 

/NOHEADER 
(/-HD) 

/SYMBOL_TABLE 
(Specify third 
output file) 

STACK = 



PAR = 

par [ : base : len] 



Effect 

No task 
header 

Create a 
.STB file 



No space 
for stack 
in . TSK file 

Spec i f y 
par ti tion 
name (set 
base virtual 
address - 
required if 
absolute; must 
also specify 
length, zero 
or maximum) 



Defaul ts 
/HEADER 



No .STB 

file 



Notes 



STACK 
word s 



256 (10) 



PAR = GEN 
If base and 
length are 
not speci f ied , 
information 
is taken from 
partition on 
the system 



Needed for 
task-bui Id ing 
referencing task 



Partition name 
must be same as 
name of the .TSK 
and .STB files 

For PI regions, 
if specifying 
base and length, 
use base = 0, 
length = or 
max imum 
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Example 7-1 has the source code for a resident common COMWP 
and a referencing task COMGP. Overlaid psects are used for 
referencing the region. The following procedure is used to create 
the resident common. 

1. Code the shared region. 

See COMWP. MAC in Example 7-1. The following notes are 
keyed to the example. 

Q The code is placed in an OVR Psect named MYDATA. This 
same Psect is used in the referencing task. 

Q This series of assembler directives is equivalent to 
128(10) .WORD 3 assembler directives. It initializes 
the first 128(10) words in the region to 3. 

Q This series of assembler directives initializes the 
next 128(10) words in the region to 6. 

2. Assemble the shared region. 

>MACRO/LIST COMWP 

3. If necessary, create the common type partition. 

We will make a partition COMWP, eight blocks = 1000(8) 
bytes long. If the partition TSTPAR already exists on 
your system, you may be able to eliminate it and then set 
up your partition. Be sure to check with your system 
manager before doing this and also be sure to put TSTPAR 
back when you are finished. 

! Check current partitions on the system 
>SHOW PARTITIONS 

'Record base address and length of TSTPAR and the type 

!of partition. Convert the values to blocks by 

'dropping the last two zeroes. (For example, 

Ibase address 123400(8) = 1234 blocks, 

Uength = 20000(8) bytes = 200(8) blocks) 

! Eliminate the partition TSTPAR 

>SET NOPARTITION: TSTPAR 

» Create the partition COMWP 

>SET PARTITION : COMWP/BASE : 1234/SIZE: 10/COMMON 
I Check to see if this worked correctly 
>SHOW PARTITIONS 
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Later, to eliminate the partition and to replace TSTPAR, 
use the commands: 



>SET NOPARTITION:COMWP 

>SET PARTITION : TSTPAR/ BASE : 1234/SIZE: 2 00/ TASK 

4. Task-build the shared region. 

To build position independent: 

> LINK/OPT IONS/ MAP/ SHARE ABLE : COMMON /N OH EADER - 
->/SYMBOL_TABLE/CODE : PIC COMWP 
Option? STACK=0 
Option? PAR=COMWP 
Option? <RET> 



The /OPTIONS switch allows you to enter options. /MAP 
indicates that you want a map file. /SHAREABLE : COMMON 
indicates that Psect names are to be placed in the .STB 
file (required to reference the shared region using 
overlaid Psects) . /NOHEADER means do not include a task 
header in the task image because this is not an executable 
task. / SYMBOL_TAB LE means make a .STB file (COMWP. STB) . 
/CODE:PIC means position independent code for a position 
independent region. STACK = means no stack space is 
needed because this is not an executable task. PAR = 
COMWP means the partition is COMWP. The Task Builder gets 
the length (for a maximum check) from the partition on the 
system. 



To build absolute: 



>LINK/OPTIONS/MAP/SHAREABLE : COMMON/NOHEADER - 

->/SYMBOL_TABLE COMWP 

Option? STACK=0 

Option? PAR=COMWP: 160000 : 20000 

Option? <RET> 

Only changes: 

1. Omit /CODE:PIC. 



2. Specify a base virtual address and a maximum 
length. The base virtual address must correspond 
to a base virtual address for an APR (e.g., 2, 
20000(8), 40000(8), 60000(8), 100000(8), 

120000(8), 140000(8), or 160000(8)). The APRs 
used must be available in all referencing tasks. 
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Install the region. 
> INSTALL COMWP 

Installs the region and also loads it into memory 
Note that this is different from an executable task 
which usually isn't loaded until it is requested. 
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O 

e 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 



♦TITLE COMWP 
♦ IDENT /Ol/ 
♦ ENABL L..C 

File COMWP ♦ MAC 



? Enable lower case 



Program which creates and initializes a common region 
which will he referenced using overlaid Psects* 

Task-build instructions: Must include /SHAREABLE * COMMON 
and /NOHEADER switches? STACK=0 and PAR^COMWP options* 
Must create *STB file* Maw be /CODEtPIC or absolute 
(default) ♦ 

The code is placed in a Psect named MYDATA 



17 


♦ PSECT 


MYDATA 


Dy GBL f OMR 


y Defaults RELyRW 


"18 


♦ REPT 


128* 


y 


Repeat count 


19 


♦ WORD 


3* 


f 


Word value of 3* 


.20 


♦ ENDR 




y 


End repeat range 


"21 


♦ REPT 


128* 


y 


Repeat count 


22 


♦ WORD 


6* 


y 


Word value of 6* 


_23 


♦ ENDR 




y 


End repeat range 


24 


♦ END 











1 




♦ TITLE 


COMGP 






2 




♦IDENT 


/Ol/ 






3 




♦ENABL 


LC y 


Enable lower case 




4 


5 + 










5 
6 


y FILE 


COMOP ♦ MAC 






7 


y 

5 This 


task get 


s the values from the static common 




8 


y region COMWP* 


It uses the technique of overlaid Psects 




9 


y to reference 


the region ♦ 






10 


y 










11 


y Task- 


-build instructions: 






12 
13 


y 
y 


>LINK/MAP/0PT10N COMGP 






14 


y 


Option? 


RESCOM^COMWP/RO 






15 


y 


Option? 


<RET> 






16 


y — 










17 




♦ MCALL 


QIOW$SyEXIT*S ? 


Swstem macros 




"18 




♦PSECT 


MYDATA DyGBLyOVR ? 


Psect used in COMWP 


•1 


19 


M=* 




y 


local symbol for start 




"20 






y 


of region 


e 


21 




♦ PSECT 


y 


Back to blank Psect 




22 


iosb: 


♦ BLKW 


2 y 


I/O status block 




23 


ARG! 


♦ BLKW 


1 y 


Argument block for 




24 






y 


error code 




25 


buff: 


♦ BLKB 


.100 ♦ y 


Output buffer 




26 


fmt: 


♦ASCIZ 


/%8D/ y 


Format string for 


°l 


27 






y 


output of data 




"28 


FERRl : 


♦ASCIZ 


/DIR ERROR ON QIQ. 


DSW » ZD/ t Directive 




29 






5 


error message 




30 


FERR2 : 


♦ASCIZ 


•I/O ERROR ON QIO* 


CODE •= %D! t I/O error 




31 






y 


message 
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32 
33 
34 
35 
36 
37 
3(3 
'39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
"49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 



N*=32* 



♦ EVEN 



Loop count - 32 
8 #s per line 



1 ines v 



START ♦ MOV 



LOOP J 



MOV 

MOV 

MOV 

C A L. L. 

QI0UI*S 

BCS 

TSTB 

BLT 



#M t R2 

#NyR5 
#BUFFyR0 
#FMT y Rl 
♦EDMSG 
#I0,WVBy#5i 
ERROR 
I0SB 
ERROR 1 



i Stay here for good write 



9 Error 
ERROR ♦ 



ERROR 1 



SETUP 



SOB 

EXIT*S 

code 

MOV 

MOV 

BR 

MOVB 
MOV 

MOV 

MOV 

MOV 

CALL 

QI0W$S 

EXIT$S 
♦ END 



RSyLOOP 



$DSW?ARG 
#FERR1 9 Rl 
SETUP 
lOSByRO 
ROy ARG 

#FERR2yRl 
#BUFF 9 RO 
#ARGyR2 
*EDMSG 
#I0*WVBy#5y' 



START 



? Starting addv of data 
y in the region 

? Loop count 

? Output buffer 

? Format string 

y Edit message 
9 9 * I OSB y y <#BUFF y R 1 y #40> 

? Check for d:i. r error 

y Check for I/O error 

y Branch on I/O error 

? Decrement counter y loop 
y back if not yet done 
y Exit 

y Move DSW to arg block 
? Addr of format string 
y Branch to $EDMSG code 
? Extend sign on I/O 
y status and place in 
y arg block 

of format string 
of output buffer 
of argument block 



y Addr 

y Addr 

y Addr 

y Edit message 
y<#BUFFyRly#40> 
y message 

? Exit 



9 Write 
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Run Session 

>INS COMWP 
>RUN COMGP 

3 3 3 3 3 3 3 3 

3 3 3 3 3 3 3 3 



3333333 3 
<f> 6666666 
6 6 6 6 6 6 6 6 
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Creating a Referencing Task 

1. Code the task, using the corresponding referencing 
technique . 

• If Psect names are kept in the .STB file of the 
referencing task, avoid Psect conflicts. 

2. Assemble the task. 

3. Task-build the task. 

• Specify shared regions using one of the following 
options: 

COMMON=common name for a system resident common 

(.STB and . TSK files must be in LB: [1,1]). 

LIBR=common name for a system resident library 
(.STB and .TSK files must be in LB: [1,1]). 
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RESCOM=common name for a user resident common 
(.STB and . TSK files in any device and any UFD 
using normal defaults) . 

RES L IB = common name for a user resident library 
(any device and any UFD using normal defaults) . 

• Append :R0 if read-only access is desired. 

:RW if read-write access is desired. 
Use "/" instead of " :" for RESCOM and RESLIB. 

• Only if the shared region is position independent, can 
you specify the base APR to be used to map the region. 
If not specified, the highest available APR or set of 
APRs is used , as needed . 

4. After installing the shared region, install and/or run the 
task . 

If the shared region is to be a system shared region, the 
•STB file and the .TSK file should be placed in LB: [1,1]. 
Otherwise, they can reside on any device under any UFD, as long as 
both files are in the same UFD on the same device. 

Read-only or read/write access affects the way the access 
bits in the page descriptor registers (PDRs) in the APRs are set 
up. A memory protect violation occurs if a task attempts to write 
to a region when it has read-only access. 
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COMGP.MAC in Example 7-1 contains the source code for a task 
to reference the shared region COMWP. Use the following procedure 
to create the task. 

1. Code the task. 

See COMGP.MAC in Example 7-1. The following notes are 
keyed to the example. 

Q The same Psect, MYDATA, is used here as in COMWP. MAC 
to set up referencing. M marks the beginning of the 
region. No initialization of the Psect can be 
performed in the referencing task. 

Q The main code is in the blank (. BLK.) Psect. 

Q Move the starting address of the region to R2. 

Q We use $EDMSG to set up each line of the display. We 
loop through once for each line, editing and 
displaying the values. 

Q The format string for $ EDMSG . %8D means convert eight 
words to signed decimal, with a tab between values. 

2. Assemble the task. 

3. Task-build the task. 

>LINK/OPTION/MAP COMGP 
Option? RESCOM = COMWP/RO 
Option? <RET> 

Link task to resident common COMWP. COMWP. TSK and 
CONWP.STB are in the current UFD on SY: . Set up 
read-only access. Use the highest available APR, APR 
7, if the region was built position independent. 

4. After installing the shared region, install and/or run the 
task . 

To do a temporary install, run, remove: 

>RUN COMGP 

To install and then run: 

> INSTALL COMGP 
>RUN COMGP 
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Deciding whether read-only or read/write access to a region 
is required is usually straightforward. If a task moves data into 
the region or changes a value in the region, read-write access is 
required. If a task moves data out of the region or just reads 
values in the region, just read-only access is required. 

However, when QIOs are issued and the buffer is in the shared 
region, things get a little tricky. Obviously, to do a read 
(e.g., from a terminal) into a buffer in the shared region 
requires write access. A write (e.g., to a terminal) from a 
buffer in the region should only require read access. However, 
because the Executive is designed for very fast, real-time 
applications, it does not check the function code for a QIO 
directive to see whether it is a read or a write. Instead it 
assumes the worst case - that all QIOs involving a buffer in a 
shared region are reads (from a peripheral device) into a buffer 
in the region, and that therefore, all QIOs require read/write 
access. This condition causes an I/O error (IE.SPR) for illegal 
user buffer. This condition does not affect Example 7-1 because 
$EDMSG creates the output string in a buffer within the 
referencing task area, and the QIOs do the writes from the 
referencing task area. 

In an example in a later module, you will see this problem 
come up. One solution is to get read/write access to the shared 
region. Another solution is to move the data from the shared 
region to a buffer in the referencing task area, and then use that 
buffer for the QIOs. A third solution is to build the task as a 
pr iv ileged task . 

Privileged tasks, similar to privileged terminals, are 
granted certain extra access to the system which nonpr iv ileged 
tasks don't have. Some privileged tasks just gain these extra 
access rights, others map to the Executive as well. Normally, the 
Task Builder builds a task as a nonpr iv ileged task. For a 
discussion of privileged tasks and how to task-build them, see 
Appendix D. 
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Example 7-2 shows a shared region (COMNP.MAC) and a 
referencing task (COMGGS.MAC) using global symbols to reference 
the shared region. Other than the difference in referencing 
technique, Example 7-2 is the same as Example 7-1. The following 
notes are keyed to the example. 

O Because the region is built with the /SHAREABLE : LIBRARY 
switch, any Psect names used in the file are not placed in 
the .STB file. Therefore, the code for the referencing 
task can be placed in the default blank (. BLK.) Psect or 
any other Psect. If the library were instead built 
/SHAREABLE: COMMON, the Psect names used in the shared 
region would all be placed in the .STB file. In that 
case, using any Psect in the referencing task which is 
also used in the shared region would cause a Psect 
conflict, causing a LOAD ADDRESS OUT OF BOUNDS 
task-builder error. 

O Tne global symbol K marks the beginning of the shared 
region . 

Q The rest of the code is the same as COMWP.MAC in Example 
7-1. 

Q Just use the global symbol K to reference the start of the 
shared region. The Task Builder sets up the linkage to K, 
as it is defined in the shared region COMNP. The rest of 
the code is the same as that in COMGP.MAC in Example 7-1. 

The tape supplied with this course also contains an example 
using virtual addresses as a referencing technique. The shared 
region is still COMNP, the same one as in Example 7-2. The 
referencing task code is in the file COMGVA.MAC. It should be in 
UFD [202,3] on your system. Check with your course administrator 
if you need help locating this example. 
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4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
r.1.6 

Oil 
18 
L 19 

20 
21 
~ r > r > 

23 
24 
25 
26 
27 
L28 



♦TITLE COMNP 
♦I DENT /Ol/ 
♦ ENABL LC 



y En3ble lower case 



File COMNP* MAC 



Program which creates and initializes a common region 
which will he referenced using global symbols or 
actual virtual addresses* 

Task-build instuctions X Must include /SHAREABLE X LIBRARY 
and /NOHEADER switches? STACK~0 and PAR-COMNP options* 
Must create a *STB file* Maw be /CODE* PIC or absolute 
< the default ) ♦ 

This program places the code in the default blank 
(♦ BLK*> Psect* It could be in any Psect* Psect 
conflicts are avoided by using the /SHAREABLE* LIBRARY 
switch on the task builder* 



k: 



Define K» a 

♦ REPT 

♦ WORD 

♦ ENDR 

♦ REPT 

♦ WORD 

♦ ENDR 

♦ END 



global 
128* 
3* 

128* 
6* 



symbol 



r Repeat count 

5 Word value of 3* 

5 End repeat range 

y Repeat count 

y Word value of 6* 

y End repeat range 



1 ♦ TITLE COMGGS 

2 ♦ I DENT /Ol/ 

3 ♦ENABL LC ? Enable lower case 

4 5 + 

5 ? FILE COMGGS*MAC 

6 5 

7 ? This task gets the values from the static common 

8 y region COMNP ♦ It uses a global symbol to reference 

9 ? the region* 

10 J 

11 y Task-build notes* 

12 ? 

13 y LINK/MAP/OPTION COMGGS 

14 y Option? RESC0M^=C0MNP/R0 

15 y Option? <RET> 

16 y- 

17 *MCALL QI0W*Sy EXIT$S ? Externa 1 system macros 
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18 
19 
20 
21 
^2 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 



IOSB: 
ARG * 

buff: 

FMT ♦ 
FERR1 * 
FERR2 J 



START * 

loop: 



♦ BLKW 

♦ BLKW 

♦ BLKB 
♦ASCIZ 

♦ A S C X HL 

♦ A S C X ~2L 
N=32* 

♦ EVEN 
MOV 



MOV 
MOV 
MOV 
CALL 
QIOW*S 
BCS 
TSTB 
BLT 

f Stay here for 
SOB 

EXIT*S 
y Error code 

error: MOV 

MOV 
BR 

ERROR i: MOVB 
MOV 



setup: 



MOV 

MOV 

MOV 

CALL 

QIOW$S 

EXIT*S 
♦ END 



2 
1 

100* 
/%8D/ 

/DIR ERROR ON 
! I/O ERROR ON 



y I/O status block 

9 Argument block for 

y error code 

r Output buffer 

? Format string for 

y output of data 
QI0» DSW = ZD/ y Directive 

y error message 
010 ♦ CODE = ZD! y I/O 

5 error message 

y Loop count ~ 32 ♦ linesy 

? 8 #s per line 



#K'yR2 

#NyR5 
#BUFF y RO 
#FMT y Rl 
$EDMSG 

#I0*WVBy#5y#ly 

ERROR 

IOSB 

ERROR 1 

good write 

RSyLOOP 



$DSWy ARG 
#FERR1 y Rl 
SETUP 
lOSByRO 
RO y ARG 

#FERR2y Rl 
#BUFFyR0 
#ARGyR2 
$EDMSG 

♦I0,WVBy#5y#l 



y Starting addrress of 
y data in the region 
y Loop count 
y Output buffer 
y Format string 
y Edit message 
y#I0SBy y <#BUFFyRly#40> 
y Check for dir error 
y Check for I/O error 
y Branch on I/O error 

y Decrement counter y loop 
y back if not wet done 
y Exit 

? Move DSW to arg block 
y Addr of format string 
y Branch to *EDMSG code 
y Extend sign on I/O 
y status and place in 
y arg block 
? Addr of format string 
y Addr of output buffer 
y Addr of argument block 
y Edit message 
y f y <#BUFF y R 1 y #40> y W r i te 
y error message 
y Exit 



START 
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Run Session 

>INS CQMNP 
>RUN COMGGS 

3 3 3 3 3 3 3 3 

3 3 3 3 3 3 3 3 



3 3 3 3 3 3 3 3 

& 6666666 
& 6666666 



Example 7-2 Resident Common Referenced With Global Symbols 

(Sheet 3 of 3) 



Example 7-3 contains a shared library, LIB. MAC, and a 
referencing task, USELIB.MAC. The shared library contains four 
simple arithmetic routines to add, subtract, multiply, and divide 
two numbers. They are all written to be reentrant, plus they can 
be called from a FORTRAN program with a standard FORTRAN 
subroutine call. Basically, this means that on entry the 
arguments are assumed to be set up as follows: 





count=3 


address 


of 


0P1 


address 


of 


0P2 


address 


of 


answer 
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For additional information on the F0RTRAN/MACR0-1 1 interface, 
see Appendix C. Each subroutine saves and restores all of the 
registers, using the system library routine $SAVAL. The 
referencing task, USELIB, calls each of the subroutines once, 
using the operands 8 (10) and 2 (10) , and displays just the answers 
for the four operations. The following notes are keyed to Example 
7-3. 

Q Each subroutine entry point is defined with a global 
symbol . 

Q Each subroutine is in a Psect of the same name as the 
subroutine. In fact, the psects are optional since the 
library is built /SHAREABLE : LIBRARY. The specified Psect 
names are not placed in the .STB file. 

O For AADD and SUBB, move the first operand to R0, perform 
the operation in R0, then move the answer to the third 
operand for return to the caller. 

Q For MULL, use Rl instead of R0, so that the product is 
limited to just Rl (16 bits). If R0 were used instead, a 
32-bit product is returned (low-order 16 bits in Rl, 
high-order 16 bits in R0) . 

Q For DIVV, a 32-bit dividend is assumed in Rn and Rn+1, so 
here it is R2 and R3 (low-order 16 bits in R3, high-order 
16 bits in R2) . Therefore, the 16-bit operand is placed 
in R3 and the high-order word is cleared. The 16-bit 
quotient, returned in R2, is then moved into the third 
operand for return to the caller. 

Q The two operands. 

Space allocated for return of the result. 

Q FORTRAN type argument block is built on the stack, in 
reverse order, so that SP points to the start of the 
block. 

Q The address in SP is moved to R5, so R5 points to the 
start of the argument block. 

Q Call each of the routines. Since R5 and the stack are not 
disturbed between calls, the same argument block can be 
used for all four calls. 

O Call the subroutine PRINT to edit the output message and 
display it for all operations. 
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3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 

©19 
©20 

21 
22 
23 
24 
25 

© 26 
©27 

28 
29 
,30 
31 
32 
w 33 
©34 
35 
36 
37 
38 
39 
40 

©42 

r43 

44 
45 
L46 
47 
48 



O 

e 



♦TITLE LIB 

♦ I DENT /01/ 

♦ ENABL LC 

File LIB ♦ MAC 



y Enable lower case 



This file contains the FORTRAN callable subroutines 
A ADD j> SUBBy MULL* and BlVVy which perform the 
appropriate integer operation* 

Ca 1 1 i rig convent i on ♦ CALL sub ( op 1 y op2 y ans ) 

Task-build instructions ♦ Must include /SHAREABLE t LIBRARY 
and /NOHEAEiER switches? STACK=0 and PAR-LIB options* 
Must create »STB file* Maw be /CODE ♦ PIC or absolute 
(default)* Using /SHAREABLE ♦ LIBRARY avoids Psect 
conf 1 icts ♦ 



aadd: : 



subb: t 



MULL ♦ 



diwj : 



♦ PSECT 


AABDyRO f I 


CALL 


SSAVAL 


MOV 


02 (R5) yRO 


Aim 


(?4(R5) yRO 


MOV 


R0y@6(R5) 


RETURN 




♦PSECT 


SUBB yRO y I 


CALL 


$SAVAL 


MOV 


02 (R5) yRO 


SUB 


04 (R5) yRO 


MOV 


ROy06(R5) 


RETURN 




♦PSECT 


MULLyROy I 


CALL 


*SAVAL 


MOV 


62 (R5) yRl 


MUL 


04 (R5) yRl 


MOV 


Rly@6(R5) 


RETURN 




♦PSECT 


niVVy RO y I 


CALL 


$SAVAL 


MOV 


@2<R5) yR3 


CLR 


R2 


niv 


@4 < R5 ) y R2 


MOV 


R2y@6<R5) 


RETURN 




♦ ENH 





I y GBL 



■ REL y CON 

y Save all registers 

y Move 1st operand 

y Add 2nd operand 

y Store result 

y Restore regs and return 



y Save all registers 

y Move 1st operand 

y Subtract 2nd operand 

y Store result 

y Restore regs and return 



y Save all registers 

y Move 1st operand 

y Multiply (answer in 

y Just Rl ) 

y Store result 

y Restore regs and return 



y Save all registers 

y Move 1st operand 

y Clear high order 16 bits 

y Hi vide 

y Store result 

y Restore regs and return 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
.10 
11 
12 
13 
14 
15 



16 

•[S 

Q 19 

20 



o 



o 
o 
© 



© 



© 
© 



21 
'2 
23 
24 
r25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 



♦TITLE USELIB 
♦ I DENT /Ol/ 

♦ENABL LC f Enable lower case 

File USELIEUMAC 

MACRO- 11 task to use the resident library LIB 

Task-build instructions* 

>L INK/MAP/OPT I ON USEL I B 
Op t i o n? RESL I B-L IB/RO 
Option? <RET> 



♦MCALL QIOW$S»EXIT*S 



opi: 

0P2J 
ANS X 

out: 
format: 

y Build 

start: 



♦ WORD 

♦ WORD 

♦ BLKW 

♦ BLKW 
♦ASCIZ 

♦ EVEN 
argument 
MOV 
MOV 
MOV 
MOV 
MOV 
C AL. L. 
CALL 
CALL 
CALL 
CALL 
CALL 
C AL. L- 
CALL 
EXIT*S 



8* 



.1. 

100* 

/THE ANSWER = 

block for si 
♦ANSy- (SP) 
#0P2»-(SP) 
#OPly-<SP) 
♦3y-(SP) 
SP?R5 
AADD 
PRINT 
SUBB 
PRINT 
MULL 
PRINT 
DIVV 
PRINT 



y System macros 

y Operand 1 

y Operand 2 

v Result 

y Output buffer 
= XD*/ y Format string 

.ib routine on the stack 

5 For result 

? Operand 2 

5 Operand 1 

y Number of arguments 

y R5-> ars* block 

? Add operands 

y Print results 

5 Subtract operands 

y Print results 

5 Multiply operands 

y Print results 

y Divide operands 

y Print results 

? Exit 



y** PRINT 



Prints the results of the operation 



PRINT 



MOV 

MOV 

MOV 

CALL 

QI0W*S 

RETURN 
♦ END 



#0UTyR0 
♦FORMAT* Rl 
♦ANSyR2 
$EDMSG 
♦I0»WVBy^5! 



START 



$ Set up for $EDMS6 



♦ 1 



Edit message 
:#0UT»R1»#40> 

message 
Return 



y Write 



Run Session 

>INS LIB 
>RUN USELIB 
THE ANSWER IS 
THE ANSWER IS 
THE ANSWER IS 
THE ANSWER IS 



10. 
6* 

16 ♦ 

4 * 
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DEVICE COMMONS 

A device common is a special type of common that occupies 
physical addresses on the I/O page. Instead of physical memory, 
the I/O page contains peripheral device registers. Therefore, a 
device common does not contain data the way a regular resident 
common does. 

A device common is really just a way of setting up addressing 
to allow a task to manipulate the device registers directly. This 
might be useful in checking out the proper commands needed to 
control a device or to check what control status registers (CSRs) 
are in use on your system (Example 7-4) . Obviously, extreme care 
must be used if you manipulate a device which is also referenced 
by any system routines (e.g., a system device driver). 

Privileged tasks which map to the Executive can also 
automatically map the I/O page. However, privileged tasks must be 
written very carefully to avoid causing additional problems for 
the running system. Device commons allow nonpr iv ileg ed tasks to 
manipulate device registers. 

Use the procedure outlined below to create a device common 
and a referencing task. The outline includes the specific steps 
for Example 7-4. It has a device common, DEVICE. MAC, which covers 
the entire I/O page. The referencing task, CSR.MAC, checks each 
address on the I/O page to find out which CSRs are in use. If a 
nonexistent CSR is found, a nonexistent memory error synchronous 
system trap (SST) results. Use the following steps to create the 
device common. 

1. Create a device common partition which includes the 
desired device register addresses. 

• Identify the addresses of the needed device registers, 
using the PDP-11 peripherals Handbook or information 
available from your hardware installation. 

• Determine the base address of the partition at a 
100(8) boundary below the first identified address. 

Mapping always begins at a 32-word block boundary. 

Example 7-4 covers all of the I/O page. On a PDP-11/70 or 
other PDP-11 with 22-bit addressing, it starts at physical 
address 17760000(8). On a system with 18-bit addressing, 
it starts at 760000(8). On a system with 16-bit 
addressing, it starts at 160000(8). 
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For a 22-bit system the command is: 

SET PARTITION: DEVICE/BASE: 177600/SIZE: 200/DEVICE 



For a 16-bit or 18-bit system, use the appropriate base 
address in 32-word blocks. 

Note that you don't need to eliminate an existing 
partition the way you did for resident commons and 
resident libraries. This is because there isn't any real 
partition already on the system, because the I/O page does 
not correspond to physical memory. 

You also don't need to create the partition until after 
you create the shared region. However, you do have to 
know its base address before you write the code for the 
device common, so that you can set up the offsets to the 
locations you plan to reference. 

Code the shared region. 

• Do not initialize any locations, since there is no 
physical memory. 

• Set up for an appropriate referencing technique to 
address the desired registers. 

Use ,=.+n or .BLKB n to get to the first address. 

Use .BLKB or . BLKW statements to reserve the 
needed space (or addresses) . 

The following note is keyed to DEVICE. MAC in Example 7-4. 

Because you access the entire I/O page, mark the start 
of the region with the global symbol FCSR. The .BLKW 
4096. directive reserves a full 4K words of addresses 
for the entire I/O page. 

Assemble the device common. 

>MACRO/LIST DEVICE 
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Task-build the device common. 

>L INK/OPTION/MAP/NOHEADER/ SHAREABLE : LIBRARY- 
-> S YMBOL_TABLE DEVICE 
Option? STACK=0 

Option? PAR=DEVICE: 160 000: 20000 
Option? <RET> 



This command task-builds the region absolute. You can 
also task-build it position independent. 

Install the device common before you run the referencing 
task. Unlike a resident common, a device common is not 
loaded into memory because it has no real contents. 
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Use the following steps to create the referencing task. 

1. Code the referencing task using the corresponding 
referencing technique. See the notes which are keyed to 
the example below. 

2. Assemble the task. 

>MACRO/LIST CSR 

3. Task-build the task to reference the device common. 

> LINK/MAP/OPT ION CSR 
>Option? RESCOM=CSR/RO 
>Option? <RET> 

4. After installing the device common, install and/or run the 
referencing task. 

The following notes are keyed to CSR. MAC in Example 7-4. 

Q Use the global symbol FCSR to reference the start of the 
device common. 

Q SST vector table with one entry for nonexistent memory. 
NONE is the address of the SST routine. (See Example 2 
for an SST example.) 

Q Two words for a range of good CSR addresses. The 

addresses are offsets into the I/O page (0(8) to 

17777(8)). FIRST is set initially with 0; LAST is 

updated on each read of a CSR. If you ever trap due to 

nonexistent memory, print the range of addresses, set 
FIRST for the first address in the next range, and 
continue . 

Q Set up for SST, using just one table entry. 

Q Count of good addresses in a range. This is used to avoid 
printing a message if a number of consecutive addresses 
are not in use. 
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Set first range to start with offset into I/O page. 

Test (or read) the word and increment R4. Control passes 
to the next instruction if the CSR is in use; an SST 
results if it is not in use. 

Increment count of good addresses. 

Check to see if you are at the end of the I/O page. 
Branch back if not. 

When at the end of the I/O page, display the last range 
and exit. 

SST routine, entered for nonexistent memory trap on the 
TST(R4)+ instruction. Check for some good addresses in 
this range. If none, do not print a message. 

Calculate offset to the last good CSR. The last one 
tested was bad, plus autoincrement incremented R4 by two . 
Therefore, the current contents of R4 are four bytes 
higher than the last good CSR. Also, convert the virtual 
address to an offset from the beginning of the I/O page. 
Move the last good CSR address to LAST. 

Edit the range message, and convert the first good and 
last good addresses to unsigned octal. Then display the 
message . 

Set up for the next range and return from the trap. The 
return picks up at line 49 (INC R5) . We want R5 to be 
zero after it is incremented, so place a -1 in R5. Set up 
the first good CSR address in FIRST as the offset into the 
I/O page corresponding to the current address in R4. R4 
has already been incremented past the CSR which is not in 
use. Return from trap at line 49, and continue check of 
CSRs , unless you have already reached the end of the I/O 
page . 

On the Run Session - This command has probably been issued 
already to create the device partition. It is included 
here for documentation purposes, and in case it has not 
been issued previously. 



330 



STATIC REGIONS 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
■21 



.TITLE DEVICE 
. J DENT /Ol/ 

♦ENABL I...C 9 Enable lower case 

9 

i File DEVICE ♦ MAC 

9 

5 This program sets up a device common for the I/O pa<3e 

9 

9 Task-bu i 1 d i nst ructions : Must i r.c.1 ude /SHAREABLE 1 L 1 BRARY 

i and /NOHEADER switches? STACK™0.» PAR-DEVICE options* 

i Must create *STB file* May be /CODE J PIC or absolute 

9 (the default) ♦ 

9 

i Install and run instructions J DEVICE must be installed 
9 before running any referencing task* 

9 

i The code is placed in the default blank Psect* Psect 

9 conflicts are avoided by using* the /SHAREAEU_E*L1'BRARY 

9 task-builder switch* 



FCSR ♦ ♦ ♦ BLKW 
♦ END 



4096* 



9 Set up area 4K words long 



1 

3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 



O 23 



♦TITLE CSR 
♦I DENT /01/ 

J + 

? File CSR* MAC 

This task displays the CSR addresses that are in use 
on your system* The addresses are listed as offsets 
into the I/O P3&e 

T a s k - b u i 1 d i n s t r u c t i o n s t 

LINK/MAP/OPTION CSR 
Option? RESCOM^DEVICE/RO 
Option? <RET> 

Install and run instructions* The device common DEVICE 
must be installed before running CSR* 



♦MCALL QIOW$SyEXIT$SySVTK$C ? System macros 
♦NLIST BEX 9 Do not list binary 

9 extensions 

9 SST vector table 

VEC* *W0RD NONE $ Nonexi stent memory 
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?4 

t 
















i J. I \ & I ♦ 


* Fil K'U 


1 


9 


1 J, 1 b t ilUUU t/ O r\ o >J M 1 fr s> 5> 


e 




1 ACT t 


♦ Ju> L.. I\ W 


1 


9 
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handle trap 




40 




ue J. U w •!> O 


ITfl 1,11 UJ „ M.K? „ JL 4 

* J.U ♦ WVJtl y WvJ m » 1 


9 9 9 9 


<#HDR*#LHDRy#40> 




41 










Display header text 
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42 
43 




MOV 


#FCSRyR4 




Set base address in 
I/O page 




44 




CLR 


R5 




Count of addrs found 


©45 




CLR 


FIRST 




Offset to first CSR 




46 










Bddr in use 




47 


J Test 


address r 


causing trap 


if not in use 




48 


1 $ * 


TST 


<R4> + 




Is this a good addr? 


a 


>49 




INC 


R5 




Yes» increment count 




50 




CMP 


#<FCSR+17776> 


yR4 


9 At end of I/O page? 




51 




BHIS 


1* 




Branch back if not wet 




52 


5 Display last 


good range and 


exi 


t 




"53 




MOV 


*1 7776 y LAST 




Put last CSR in LAST 




54 




MOV 


#BUFF*R0 




Set up for $EDMSG 


© 


55 




MOV 


♦MESrRl 






56 




MOV 


♦FIRST ?R2 








57 




C AL. L. 


$EDMSG 




Edit range message 
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9 9 9 9 


<#BUFF 9RI9 *40> 
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Display range message 
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EXIT$S 
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? SST 
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"64 


none: 


TST 


R5 
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65 










this range? 


.66 




BEQ 


OUT 




None? nothing to print 




"67 




MOV 


R4»R3 




Calculate offset to 


o 


68 










last good CSR 


69 




SUB 


#<FCSR+4>»R3 






© 


L 70 




MOV 


R3f LAST 




Put last CSR in LAST 


71 




MOV 


♦BUFFyRO 




Set up for $EDMSG 
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MOV 
MOV 
CALL 



QIOW*S 



#MESyR.l y 
♦FIRST y R2 ? 

$EDMSG y Edit r3nsie mess3de 

#I0,WVBy#5y#ly y y y <#BUFF y Rl y #40> 



y Display ranae message 



? Set addresses 
out: MOV 



and counters for continued search 
#-lyR5 y Initialize count to -1 



y since RTT returns to 
y INC R5 instruction 



85 



MOV 
SUB 
MOV 
RTT 
♦ END 



R4yR3 y Set up first sfood CSR 

#FCSRyR3 > in FIRST 

R3y FIRST y 



y Return from trap 

START 



>SET PARTITION t DEVICE/BASE I 177600/SIZE 5 200/DEVICE 
>INS DEVICE 
>RUN CSR 

#*CSR'S IN USE ON system:** 
(ADDRS ARE OFFSETS INTO I/O PAGE) 



CSR'S 


000020 


THROUGH 


000106 


ARE 


IN 


USE 


CSR'S 


004200 


THROUGH 


004236 


ARE 


IN 


USE 


CSR'S 


005000 


THROUGH 


005776 


ARE 


IN 


USE 


CSR'S 


010200 


THROUGH 


010376 


ARE 


IN 


USE 


CSR'S 


010500 


THROUGH 


010526 


ARE 


IN 


USE 


CSR'S 


012200 


THROUGH 


012376 


ARE 


IN 


USE 


CSR'S 


012440 


THROUGH 


012476 


ARE 


IN 


USE 


CSR'S 


012516 


THROUGH 


012516 


ARE 


IN 


USE 


CSR'S 


013000 


THROUGH 


013776 


ARE 


IN 


USE 


CSR'S 


016300 


THROUGH 


016352 


ARE 


IN 


USE 


CSR'S 


016400 


THROUGH 


016452 


ARE 


IN 


USE 


CSR'S 


016500 


THROUGH 


016506 


ARE 


IN 


USE 


CSR'S 


016700 


THROUGH 


016752 


ARE 


IN 


USE 


CSR'S 


017170 


THROUGH 


017176 


ARE 


IN 


USE 


CSR'S 


017340 


THROUGH 


017356 


ARE 


IN 


USE 


CSR'S 


017400 


THROUGH 


017416 


ARE 


IN 


USE- 


CSR'S 


017440 


THROUGH 


017476 


ARE 


IN 


USE 


CSR'S 


017514 


THROUGH 


017526 


ARE 


IN 


USE 


CSR'S 


017546 


THROUGH 


017546 


ARE 


IN 


USE 


CSR'S 


017560 


THROUGH 


017676 


ARE 


IN 


USE 


CSR'S 


017740 


THROUGH 


017752 


ARE 


IN 


USE 


CSR'S 


017760 


THROUGH 


017776 


ARE 


IN 


USE 
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Appendix F contains information about several more advanced 
shared region topics. It includes a discussion of: 

• Overlaid shared regions 

• Referencing several shared regions from one referencing 
task 

• Handling interlibrary calls 

• Cluster libraries 

Most of the techniques discussed are more appropriate for the 
advanced MACRO-11 programmer who is running into virtual address 
limitation problems. cluster libraries are designed to save 
virtual address space in tasks which use DIGITAL layered products, 
such as FORTRAN , Forms Management Services ( FMS) , and File Control 
Services (FCS) . If you write FORTRAN programs which use these 
products, you may find it useful to read just the last few pages. 
These cover the procedure for task-building a task which 
references two or more DIGITAL supplied resident libraries as a 
set of cluster libraries. 

Now do the tests/exercises for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either the on-line files 
(should be under UFD [202,2]) or the printed copies in the 
Tests/Exercises book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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DYNAMIC REGIONS 



INTRODUCTION 

The last module discussed how to use the Task Builder to 
create and access static regions. It is also possible to create 
and access regions while a task is executing. Such regions are 
called dynamic regions. The memory management directives allow a 
task to create and access dynamic regions and to access existing 
static or dynamic regions. In addition, they offer a facility for 
creating private regions and for allowing other tasks to access 
these regions. 



OBJECTIVES 

1. To write tasks which create a dynamic region and access 
dynamic and/or static regions 

2. To write tasks which dynamically control their mapping 

3. To write tasks which create a private dynamic region and 
allow one or more other tasks to access the region. 



RESOURCE 

• RSX-1 1M/M-PLUS Executive Reference Manual , Chapter 3 plus 
specific directives in Chapter 5 
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SYSTEM FACILITIES 

Sometimes a task's needs for memory and for shared regions 
aren't known until run time, or the needs may change at run time. 
Examples are: 

1. A task (e.g., an editor) needs a temporary work buffer for 
only part of the time the task is active. 

2. A task needs a shared region or work buffer, but its size 
depends on the needs of the user running the task (e.g., 
the size of an input file) . 

3. A task creates a shared region and wants to control access 
to it by other tasks. 

4. A task wants to create a shared region in a system 
controlled partition (e.g., GEN) instead of in a dedicated 
common type partition. Then when the shared region isn't 
needed, the space is automatically available for other 
system needs (tasks, etc.). 

5. A task needs to map to two different shared regions at 
different times, but has only one 4K word virtual address 
window available. 

Special directives, called memory management directives, are 
available on mapped systems to allow tasks to perform the 
following functions. 

• Create regions in system controlled partitions 

• Attach/detach from a region 

• Create/eliminate virtual address windows 

• Map/unmap a virtual address window to an attached region 

• Obtain information about its mapping from the system. 

The memory management directives are a SYSGEN option. 
Therefore, if users on a system plan to use them, they must be 
included in the Executive at SYSGEN time. Check with your system 
manager to find out if they have been included on your system. 
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avaiJble^L 1 ^ directives which are 

Table 8-1 Memory Management Directives 
Function 



MACRO-11 
ATRG$ 
CRAW$ 
CRRG$ 
DTRG$ 



Attach Region 

Create Address Window 

Create Region 

Detach Region 

Eliminate Address Window ELAW$ 
Get Mapping Context GMCX$ 
Map Address Window MAp$ 
Receive by Reference RREF$ 
Send by Reference SREFS 
Unmap Address Window UMAP$ 
Specify Receive by 

Reference AST SRRA$ 
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REQUIRED DATA STRUCTURES 

Each memory management directive requires that you set up one 
of two data structures within your task - a region definition 
block (RDB) or a window definition block (WDB) . The RDB and the 
WDB are the interface between the user task and the Executive. 
Their contents change dynamically as regions are created and 
accessed. In general, once the WDB and/or the RDB are set up, the 
actual memory management directive macro calls are completely 
straightforward. Their format is either: 

xxxx$x wdb 
or 

xxxx$x rdb 
where 

wdb - the label or address of the WDB 
rdb - the label or address of the RDB 



Examples: 

CRAW$C WDB 
CRRG$S #RDB 1 

As with other executive directives, the $, $C , or $S form of each 
directive may be used. 

Region Definition Block (RDB) 

An RDB contains information needed to create a region and/or 
to attach to a region in a system controlled partition. The RDB 
is used by the following directives. 

1. Attach Region (ATRG$) 

2. Create Region (CRRG$) 

3. Detach Region (DTRG$) 
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ARRAY 
ELEMENT 

irdb (1) 
irdb (2) 
irdb (3) 
irdb (4) 
irdb (5) 
irdb (6) 

irdb (7) 
irdb (8) 



RDBBK$ SYMBOLIC 
ARGUMENT OFFSET 

R.GID 
siz R.GSIZ 



R.GNAM 



par 



sts 



pro 



R.GPAR 

R.GSTS 
R.GPRO 



BLOCK FORMAT 



BYTE 
OFFSET 





REGION ID 



SIZE OF REGION (32W BLOCKS) 



NAME OF REGION (RAD50) 



- 6 



REGION'S MAIN PARTITION NAME (RAD50) — 12 



REGION STATUS WORD 



REGION PROTECTION WORD 



10 



14 



16 



Figure 8-1 The Region Definition Block 
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Figure 8-1 shows the layout of the RDB along with the 
symbolic offsets. Use the RDBBK$ macro to create and initialize 
an RDB. Figure 8-1 also shows the RDBBK$ arguments for the 
various RDB elements. The meaning of the elements is as follows. 

• Region ID - a unique number assigned to a region when your 
task attaches to a region. The number associates the task 
with the region and is returned by the Executive after 
your task attaches to a region. 

• Size of Region - the size of a region to be created, in 
32-word blocks. It is also returned by the Executive when 
attaching to an existing region. 

• Name of Region - up to six characters. It is assigned 
when a region is created and used when attaching to a 
region . 

• Region's Main Partition Name - the name of the system 
controlled partition. 

• Region Status Word - used by the user task to send 
information to the Executive when creating or attaching to 
a region. Also used by the Executive to return status to 
the task after a memory management directive is executed. 
See Table 8-2 for a list of the various bits and their 
meanings . 

• Region Protection Word - analogous to the file protection 
word, controlling access to regions. As shown below, it 
is set up with the same format (RWED for read, write, 
extend, delete) within each category; or: system, owner, 
group, and world. 

World Group Owner System 

DEWR DEWR DEWR DEWR 

1110 1110 0000 0000 = 167000(8) 



A '1' means access is denied, a '0* means access is 
permitted. So the example means that world and group have 
just read access, and owner and system have all accesses. 
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Table 8-2 



Bllili^ 

Symbol Value Set By 

RS.CRR 100000 System 

RS.UNM 40000 System 

RS.MDL 200 User 

RS.NDL 100 User 

RS. ATT 40 User 

RS.NEX 20 User 

RS . DEL 10 User 

RS.EXT 4 User 

RS.WRT 2 User 

RS ."RED 1 User 



Region Status Word 
Definition 

Region successfully created 

At least one window unmapped on a 

lllll^ 

Mark region for deletion on last 

illilll^ 

Created region not deleted on last 

llilillM 

Attach to created region 
Created region not extendable 
Delete access desired on attach 
Extend access desired on attach 
Write access desired on attach 
Read access desired on attach 
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Creating an RDB in MACRO- 1 1 

The format for the RDBBK$ macro call is: 
RDBBK$ siz ,nam , par ,sts ,pro 



No argument is provided for the region ID because it is 
always returned by the Executive and is never specified by the 
user. See Table 8-2 for a list of the region status word bits, 
including their symbols and meanings. We will discuss these 
further when we discuss the individual directives. Any 
information not filled in at assembly time using the RDBBK$ macro 
can be filled in using direct MOVs at run time. 

Examples : 

To create an RDB for use in creating a region with: 

Size in 32(10) word blocks = 2 

Region name = MYREG 

Partition name = GEN 

Region to be attached on create 

Region to be marked for delete on last detach 

Write access desired on attach 

Owner to have all privileges and group to have read 
pr ivileges . 

RDBBK$ 2, MYREG, GEN, <RS. ATT! RS.MDL! RS.WRT> , 177 017 
Expansion : 

.WORD ; Region ID 

.WORD 2 ; Region size 

. RAD50 /MYREG/ ; Region name 

. RAD50 /GEN / ; partition name 

.WORD <RS. ATT! RS.MDL! RS.WRT> ; 000242(8) Region status 

; word 

.WORD 177017 ; Region protection word 
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The example below shows the use of a MOV instruction to set 
the region size at run time. 

To create an RDB for use in creating a region with: 

Size in 32(10) word blocks = 1000 (8) 
Region name = XXXX 

Partition name = same as task is installed in 

Region status = do not delete, desired access to be filled in 
before attaching 

World to have no privileges, all others to have all privileges 
RDBBK$ 0,XXXX, ,RS. NDL, 170 00 



Ex pansion : 



.WORD 

.WORD 

. RAD50 

.WORD 

.WORD 

.WORD 






/XXXX 

0,0 

RS. NDL 

170000 



/ 



Region ID 

Region size 

Region name 

partition name 

100(8), Region status word 

Region protection word 



MOV #1000 , RDB+R .GSIZ ; Set region size at run time 
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Window Definition Block (WDB) 

A WDB contains information needed to create a virtual address 
region and to map a virtual address window to an attached region. 
The WDB is required for the following directives. 

1. Create Address Window (CRAW$) 

2. Eliminate Address Window (ELAW$) 

3. Map Address Window (MAP$) 

4. Unmap Address Window (UMAP$) 

5. Send by Reference (SREF$) 

6. Receive by Reference (RREF$). 

Figure 8-2 shows the layout of the WDB along with the 

symbolic offsets. Use the WDBBK$ macro to create and initialize a 

WDB. Figure 8-2 also shows the WDBBK$ arguments. The meaning of 
the elements is as follows. 

• Window ID - A number which identifies the window block in 
the task header which describes the window. Window is 
used for the task window. Windows 1-7 are used for 
additional windows set up by the Task Builder, for 
overlays and static regions, and for windows created 
dynamically. The window ID is returned by the Executive 
after a Create Address Window directive. 

• Base APR - The base APR to be used in mapping the window, 
which sets the base virtual address. 

• Base Virtual Address - The base virtual address in octal; 
returned by the Executive after a Create Address Window 
directive . 

• Region ID - The region ID, used to identify the region 
when mapping a virtual address window to a region. It is 
returned by the Executive in the RDB after an Attach 
Region directive. You must move the value returned from 
the RDB to the WDB before mapping to the region. 

NOTE 

The Task Builder option WNDWS=n must be used 
to specify the additional number of window 
blocks needed for dynamic windows. 
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ARRAY WDBBK$ SYMBOLIC 

ELEMENT ARGUMENT OFFSET 



iwdb (1) 
iwdb (2) 
iwdb (3) 
iwdb (4) 
iwdb (5) 
iwdb (6) 
iwdb (7) 
iwdb (8) 



apr 



rid 
off 
len 
sts 
srb 



W.NID 
W.NAPR 
W.N B AS 

W.NSIZ 

W.NRID 

W.NOFF 
W.NLEN 
W.NSTS 
W.NSRB 



BLOCK FORMAT 



BASE APR 



WINDOW ID 



VIRTUAL BASE ADDRESS (BYTES) 



WINDOW SIZE (32W BLOCKS) 



REGION ID 



OFFSET IN REGION (32W BLOCKS) 



LENGTH TO MAP (32W BLOCKS) 



WINDOW STATUS WORD 



SEND/RECEIVE BUFFER ADDRESS 



BYTE 
OFFSET 



10 



12 



14 



16 



Figure 8-2 The Window Definition Block 



• Offset in Region (32-word blocks) - The offset within the 
region at which mapping is to begin. It allows a task to 
map to different portions of a region. 

• Length to Map (32-word block) - The length within the 
region to be mapped. It defaults to the shorter of the 
space remaining in the region and the size of the window. 



Window Status Word - Used by the user task to send 
information to the Executive when creating and mapping 
windows. It is also used by the Executive to return 
status to the user task after a directive is executed. 
Table 8-3 lists the various bits and their meanings. 

Send/Receive Buffer Address - The address of an 8-word 
buffer for sending or receiving data as part of the Send 
by Reference and Receive by Reference directives. 
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Creating a WDB in MACRO- 1 1 

The format of the WDBBK$ macro is: 
WDBBK$ apr ,siz,rid,off,len,sts,srb 



Note that no argument is provided for either the window ID or 
the base virtual address, because these elements are always 
returned by the Executive. Table 8-3 shows a list of the window 
status word bits, including their symbols and meanings. We will 
discuss these further when we discuss the individual directives. 



Table 8-3 Window Status Word 



Symbol 
WS. CRW 
WS . UNM 

WS. ELW 

WS.RRF 
WS.64B 



WS.MAP 



Octal 
Value 

100000 

40000 

20000 



200 



Set By 
System 
System 

System 



10000 System 
400 User 



User 



Definition 

Address window successfully created 

At least one window unmapped by a 
CRAW$, MAP$ or UMAP$ directive 

At least one window eliminated in 
a CRAW$ or ELAW$ directive 

Reference successfully received 

Defines permitted alignment for 
offset start within the region 

for 256-word alignment (8 blocks) 

1 for 32-word alignment (1 block) 

Window to be mapped in a CRAW$ or 
RREF$ directive 



WS.RCX 


100 


User 


Ex it 


WS. DEL 




User 


Send 


WS. EXT 




User 


Send 


WS.WRT 


sinks 


User 


Send 


WS.RED 




User 


Send 
read 
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Examples : 

To create a WDB to describe a window with the following: 
APR = 7 

Size in 32(10) word blocks = 100(10) 

Region is to be mapped in a CRAW$ or RREF$ directive 
Map with read access. 



WDBBK$ 



7,100. ,0,0,100. ,<WS.MAP!WS.RED> 



Expansion : 

.BYTE 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



0,7 



100. 




100 . 

WS.MAPIWS.RED 





Window ID, APR 

Base virtual address 

Leng th 

Region ID 

Offset in region 

Length in region 

000201(8), window status word 

Send/Receive buffer address 



To create a WDB to describe a window with the following 
character istics : 

APR = 5 

Size in 32(10) word blocks = 200 (8) 

Map starting at offset of 5 blocks in region and map 
10(10) blocks 

Send with delete and write access. 



WDBBK$ 



5, 200, 0, 5, 10. ,<WS. 64B! WS.WRT! WS. DEL> 



Ex pansion : 

.BYTE 0,5 

.WORD 

.WORD 200 

.WORD 

.WORD 5 

.WORD 10. 

• WORD WS. 64B! WS.WRT! WS 

.WORD 



Window ID, APR 
Base virtual address 
Window length 
Region ID 
Offset in region 
Length in region 
DEL ; 000412(8), Window status 
word 

Send/Receive buffer address 
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CREATING AND ACCESSING A REGION 

Use the following procedure to create and access a region. 

1. Create the region (Create Region directive). 

2. Attach to the region (Attach Region directive). 

3. Move the region ID from the RDB to the WDB . 

4. Create a virtual address window (Create Address Window 
directive) . 

5. Map the virtual address window to the region (Map Address 
Window directive) . 

6. Use the region. 

7. Detach from the region (Detach Region directive or task 
ex it) . 

Steps 1 and 2, and also steps 4 and 5 can each be combined in 
a single directive call. Step 4 can be performed earlier, if 
desired. To access an existing region, begin with step 2. 

If you don't remember what windows and regions are, or what 
attaching and mapping mean, look over the sections on Windows and 
Regions in the last few pages of Module 5 on Memory Management. 

The use of each directive in the procedure above is detailed 
on the following pages. The discussion includes the purpose of 
the directive, important input and output parameters, and notes 
about its use. For a complete discussion of each directive, see 
Chapter 5 of the RSX-1 1M/M-PLUS Executive Reference Manual . For 
additional information on the memory management directives, see 
Chapter 3 of the same manual. 
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Creating a Region 

When you create a region, the Executive allocates space for 
it in a system controlled partition. Use the Create Region 
directive (CRRG$) with the following RDB input parameters. 

• Size of region (in 32(10) word blocks) 

• Name of region (becomes a private region if no name) 

• Name of partition (defaults to partition of task) 

• Region status word - mark for delete or do not delete 
(default is mark for delete) 

• Region protection word - determines permissible access to 
reg ion . 

The only RDB output parameter is the RS.CRR bit in the region 
status word. It is set if the region is successfully created, and 
cleared if not. Normal Executive directive status is returned as 
well (carry set for error, clear for success; DSW contains 
directive status word). If the region already exists, success 
status is returned. Therefore, RS.CRR can be used to tell whether 
the region was in fact created, or whether it already existed. 

Any task which passes the protection test can attach to a 
named region. For unnamed (private) regions, only tasks which are 
specifically attached by the creator of the region may attach to 
it. Therefore, for a private region, the creator completely 
controls which tasks attach to it and their access rights as well. 

By default, or if RS.MDL is set in the region status word, 
the region is deleted when the last attached task detaches from 
the region. Named regions are left in existence after the last 
detach if RS.NDL is set in the region status word when the region 
is created. Unnamed (private) regions are always marked for 
delete (deleted on last detach) . There is no explicit Delete 
Region directive. 

If the RS.ATT bit is set in the region status word, the 
Executive also attempts to attach the task to the region. In this 
case, additional RDB input parameters are required, and additional 
output parameters are returned. Attaching to a region is 
discussed after Example 8-1. 
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Example 8-1 shows how to create a named region which is left 
in existence on last detach. The following notes are keyed to the 
example. 

O Set U P tne RDB. RS.NDL set specifies that the region is 
to be left in existence. 

World Group Owner System 
DEWR DEWR DEWR DEWR 

Region protection word - 1111 0000 0000 0000 (2) 

1 7 (8) 

- Bit set means access is to be denied. 

Q Issue the directive to create the region, specifying the 
RDB address as the only argument. Here we use the $C form 
of the directive. Any form is allowed. 

Q Check for a directive error. 
Q Display message and exit. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
'12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 

© 26 
©27 

[28 
© 29 

L 30 
31 
32 
33 
34 
35 
36 
37 
38 
39 



♦ TITLE CRERG 

♦ I DENT /Ol/ 
♦ ENABL LC 

i + 

9 File CRERG* MAC 

V 

? CRERG creates 3 named 
f leaving the region in 



y Enable lower case 



region? and 
existence ♦ 



rdb: 

9 
P 



smes: 

LSMES 
BUFF J 

efmt: 



START 



r hrror 
ERR i 



♦ MCALL 
♦ MCALL 
RDBBK* 

Define 



exits y 



y System macros 



♦ASCII 
~ ♦ -SMES 

♦ BLKB 
♦ASCIZ 

♦ EVEN 

CRR6*C 

BCS 

QIOWSC 

EXIT*S 

code 

MOV 

MOV 

MOV 

CALL 

QI0W*S 

EXIT$S 

♦ END 



EXITfcS y RDBBK* y CRRG*C 
QI0W*CyQI0W$S 

1 00 y MYREG y GEN y RS ♦ NDL y 1 70000 
region with? 
Size = 100 (32 ♦ word blocks) 

Name = MYREG 

Partition -- GEN 

Protection ~ WO * None ySY* RWED 

OW * RWED y GR ♦ RWED 
Do not mark for delete on last detach 
/CRERG SUCCESSFULLY CREATED MYREG/ 



SO ♦ 5 $EDMSG buffer 

/ERROR IN CREATING REGION ♦ DSW = 



ZD ♦ / 



RDB 
ERR 

I0,Wv"By5 



#EFMT»R1 

#*DSWyR2 
♦BUFFyRO 
$EDMSG 

#I0»WVB»#5»#1 



START 



y Create region 
? Branch on dir 
<SMESy LSMES y40> y 



error 
Write 



success 
Exit 



message 



y Set up for $EDMSG 



Edit error message 
< # B U F F y R 1 y # 4 > ? Write 
message 
Exit 



Run Session 
>RUN CRERG 

CRERG SUCCESSFULLY CREATED MYREG 



Example 8-1 Creating a Named Region 
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Attaching to a Region 

When you attach your task to a region, the Executive creates 
a logical connection between the two. The region can be either a 
dynamic region or a static region. Use the Attach Region 
directive (ATRG$) with the following RDB input parameters: 

• Region name 

• Region status word (indicating R,W,E,D access) 
The following RDB output parameters are returned: 

• Region ID 

• Region size 

The region ID is needed later in order to map a virtual 
address window to the region. The region size is of interest when 
attaching to an already existing region whose size may not be 
known . 

Attaching can also be done as part of the Create Region 
directive (CRRG$) , if the RS.ATT bit in the region status word is 
set when the Create Region directive is issued. In fact, for an 
unnamed region, attaching must be done as part of the Create 
Region directive, since there is no region name to be used in a 
separate Attach Region directive. 

A task can detach from a region by using an explicit Detach 
Region directive (DTRG$) or by exiting (the Executive detaches the 
task) . if a task is changing a region from do not delete to mark 
for delete, an explicit detach is required with RS.MDL set in the 
region status word. If the task exits without issuing an explicit 
detach, the Executive detaches the task but does not mark the 
region for delete. Once a region is marked for delete, it is 
deleted when the last attached task detaches from it. Once it is 
marked for delete, it cannot be changed to "do not delete." If a 
fixed task exits without issuing an explicit detach, no detach is 
performed by the Executive. 
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Creating a Virtual Address Window 

When you create a virtual address window for a task, the 
Executive initializes a window block in the task header. It also 
checks to ensure that this is the only window that uses the 
specified range of virtual addresses, unmapping and eliminating 
any window that overlaps that range. Use the Create Address 
Window directive (CRAW$) with the following WDB input parameters. 

• Base APR number 

• Window size (in 32(10) word blocks) 

The following WDB output parameters are returned: 

• Window ID assigned by the system (1-7) 

• Base virtual address 

The space for the additional window blocks in the task header 
must be reserved at task-build time using the WNDWS=n option. N 
is the number of additional windows needed for windows created at 
run time. If extra space is not allocated, an address window 
allocation overflow error (IE.WOV = -85.) results. 

The window is also mapped to a region if bit WS.MAP is set in 
the window status word when the Create Address Window directive is 
issued. in that case, addition input parameters are needed. See 
Mapping to a Region in the following section. 

The Eliminate Address Window (ELAW$) directive can be used to 
explicitly eliminate a virtual address window. in general, it is 
not used, because creating a new window automatically eliminates 
any overlapping window. 



Mapping to a Region 

When you map a virtual address window to a region, the 
Executive creates a logical connection between the virtual address 
window and the region. Any attached region can be mapped. In the 
process, the memory management registers are loaded so that 
references to virtual addresses in the window access the region. 
This is assuming, of course, that the task keeps control of the 
CPU. The APRs are reloaded every time a new task takes control of 
the CPU. 
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Use the Map Address Window directive (MAP$) to map a window 
to a region, with the following WDB input parameters. 

• Region ID - Returned to RDB by Attach (move from RDB to 
WDB) . 

• Offset into Region - in 32-word blocks, used to start 
mapping at an offset from the start of the region. This 
must be a multiple of 8(10), unless WS.64B is set in the 
window status word. If WS.64B is set, any whole number 
may be specified. 

• Length to Map - If specified, must be less than, or equal 
to, either the length of the window or the length 
remaining in the region, whichever is shorter. If 
defaulted, it is set to the shorter of the two. 

• Window status word - actual access desired (read-only, or 
read/write). Read-only is always requested by default. 

The only WDB output parameter generally used is the length 
actually mapped. If the window is already mapped, it is first 
unmapped by the Executive. You can also use the Unmap Address 
Window directive to explicitly unmap a window. Mapping can also 
be done as part of the Create Address Window directive (CRAW$). 

The type of access desired is used here in addition to when 
you attach to the region, because several different windows in the 
task may map the same region. Some of the windows may need 
read-only access, others may need read/write access. In that 
case, you must attach with read/write access, and then you may map 
each window with either read-only or read/write access. 
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Example 8-2 shows how to create a region and place data into 
it, leaving it in existence upon exit. Example 8-3 shows how to 
attach to that region, read and display the data, and then detach 
and mark it for delete. One run session covers both examples. 
The following notes are keyed to Example 8-2. 

Task-build with the WNDWS=1 option, allocates space in the 
task header for one additional window block. 

We use the $ form of the memory management directives. 

RDB for region. RS.ATT set means Create Region directive 
will both create the region and attach to it. 

WDB for virtual address window. The third argument is for 
the region ID, which will be filled in at run time, after 
the task attaches to the region. In the window status 
word, WS.MAP means that the Create Address Window 
directive will both create the window and map it to the 
region. WS.RED is automatic, even though not specified. 

Create region and attach. Use DIR$ since you are using 
the $ form of the directive. 

Move region ID, returned in RDB after attach, into WDB for 
mapping . 

Create a virtual address window and map it to the region. 

The virtual address window begins with APR 7; therefore, 
the base address in the window is 160000(8), corresponding 
to the base address in the region. 

Place a byte count, 400(10), in the first word in the 
region. This is just one way to communicate this 
information to other tasks which access the region. The 
length of the region is returned when a task attaches to 
the region. You could use this as an alternate way to 
pass information about the amount of data. 

Move 100(10) words of ASCII "AB" and 100(10) words of 
ASCII "12" into the region. This gives you 200(10) words 
or 400(10) bytes of data. 

Display a successful creation and initialization message 
at the terminal . 

Detach from the region and then exit, leaving the region 
in ex istence . 
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6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 



50 
51 
52 
53 
54 
55 



♦ TITLE CREURG 
♦ IDENT /Ol/ 
*ENABL LC 



* Enable lower case 



File CREURG* MAC 



9 Program to create a named region (attached on creation)? 

f create a virtual address window (mapped on creation)? 

y place ASCII d3ta in to the region? detach from the 

y region and exit? leaving the region in existence* 
y 

y Task-build instructions? 

y 

y >LINK/0PTI0N/MAP CREURG 

y Option? WNDWS^l 

y OPTION? <RET> 



REG ♦ 
y 



WSW 

rdb: 

y 

WIN* 



wdb: 

y 

DET* 

I0SBJ 
DNMES * 

LDNMES 
y Error 
FCRRER i 

fcrwer: 
fgiode: 
fqioie: 
fdeter: 

buff: 



♦ MCALL 
♦ MCALL 

CRRG* 

Define 



EXIT*S y RDBBK* y UDBBK* y CRRG* y CRAW* 
DTRG*yDIR*yQIOW*SyaiOW*C 



RDB ?DPB 
region with* 
Size 
Name 

Partition 
Protection 



for create region 



word blocks) 



= <RS* 
RDBBK* 



= 100 (32* 
= MYREG 
- GEN 

= WO ♦ None y S Y ♦ RUED y 
OW ♦ RWED y GR ♦ RWED 
Do not mark for delete on last detach 
Attach with ready write and delete access 
NDL ! RS * DEL ! RS * RED ! RS ♦ WRT ! RS ♦ ATT> 
100 y MYREG y GEN yWSWy 170000 



CRAW* WDB 9 DPB far create address window 

Define window with* 

APR = 7 

Size ~ 100 (32* word blocks) 

Offset in region « (32* word blocks) 
Length in region = 100 (32* word blocks) 
Map on create with read/write access 
WDBBK* 7 y 1 00 y y y 1 00 y <WS * MAP ! WS * WRT> 



DTRG* 



RDB 



y DPB for detaching 
y from region 
2 y I/O status block 

/CREURG HAS CREATED AND INITIALIZED THE/ 
/ REGION/ 



♦ BLKW 

♦ ASCI I 

♦ ASCI I 
- ♦ -DNMES 
format strings 

*ASCIZ /ERROR CREATING REGION* DSW ~ %D*/ 
*ASCIZ /ERROR CREATING WINDOW* DSW « %D*/ 
*ASCIZ /DIRECTIVE ERROR ON QIO* DSW « %D*/ 
*ASCIZ !I/0 ERROR ON QIO* CODE = %D* • 
*ASCIZ /ERROR DETACHING FROM REGION* DSW = %D*/ 



♦ BLK'B 



80* 



y Output buffer 



Example 8-2 Creating a Region and Placing 
Data in it (Sheet 1 of 2) 
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56 




♦ every 






e 


57 


S FAR l ♦ 


DIR$ 


♦REG 9 


Create region and 3tt3ch 


o 


58 




BCS 


ERR1 r 


Check for error 


59 




MUV 


RDB+R ♦ GID y WDB+W ♦ NRID y Move region IB 


60 








into WDB 


o 


61 




DIR$ 


JLI IT 11 * 

♦WIN t 


Create window and map 


o 


62 




BCS 


rr Ci E!t s 


Check for error 


^ 63 




MOV 


♦1 60000 »Rb 9 


Set base addr in region 


©64 




MOV 


#400 »»(Kj)t 9 


Move byte count to 1st 




65 








woru xii t cf sa x n 




~ 66 




nuv 


* 1 A A _ DA i 

* X Ou ♦ 9 Iw y 


♦ of words of ' AB ' d3ta 




6/ 


1 nrtP ♦ 


nuv 


.4 " Aft . ( p*! ^4. s 


M n u cs v\ f- 4* f\ t\t*% cf 1 f> r*t 

nove cnor» t>u 1 caiui 1 


as 


oo 






pa . 1 nnp > 


i.1 tr l_ 1 fc? Ill tf 1 1 U L. U IJ 1 1 U tr I ol IU 


ZO 
07 








XUUr' IJI11/XX UUI It? 


/ U 




nuv 


A 1 A A .. C'A £ 

* X UU ♦ y rw y 


♦ Ol WOrQS OT XxC QoVo 




7 1 


Luur tf * 


nuv 


f li.'f\Kj/t 9 


Move chars to region 


w 


79 




c? nR 


pa . 1 nnpp i 
IW 9 LUUr JEJ y 


loop uriT/XX uorie 


/ o 




U X U W -P L- 


Tfi lllin cr *i TnOD. 

x U ♦ WvJtf y »j y 1 y y J. UbJtf 9 


_ /lUIMC'C _ 1 flMMCO _ A A"*-. 

9 ••.JUNnln.b y LliNntb y »tU.-- - 


"7 A 




BCS 


r** i™i **y y'i * 

fc.r\K3Ll y 


Branch on dir error 








TSTB 


xUb£> y 


Check for 1/0 error 








BL I 


CDD7T £ 

bhnol y 


Branch on 1/0 error 


/ / 




LlxR* 


* T"l IT T £ 

iFLifc. 1 y 


Detach f roiii ression 


/ O 




BCS 


cop/ i 
cf\r\'*T y 


Check for error 




7(3 




CVTT4C 

Lax 1 »b 








Ci A 


t E r ro r 


code 








O J. 


c r\ i\ x ♦ 


nuv 


dbPTPPPP o P 1 & 
Trr u»r\r\cp» y Pi x y 






82 








111 c? S> s> o 3 Ir 




83 




Ft P. 


onwciAiA y 


D f Ol ILM wU t. UIIIIIIUII L.U<mIc^ 




84 


i™ r\ r\ ju. ♦ 


Mnu 
nuv 


AnrppuFP-Pl * 
rr I/Iawla 71A * y 


Pt^dja'i'ci t.i -i r'i r{ o i.i iri£)<2c::aefo 
wf cfoucr wj.im.juw 1 1 1 v.. n> o 




85 




RP 


QWnFPP £ 
onucr\r\ y 


JD 1 o 1 ll_ 1 1 If U t. U III III U 1 1 LUUc 




86 


crsr\OJL< ♦ 


MflU 


*r u x ux'C. y i\ x y 


QI0 directive itiessa^e 




87 






SHOERR y 


Branch to common code 




88 


rppi; T ♦ 


Mnu 

1 lUV 


lOSByRO y 


Extend si«Jn on status 




89 




nuv 


R0y*DSW y 


and move to 3rd block 




90 




uni 1 

nuv 


♦FQIOIEyRl y 


QI0 I/O error 




91 




BR 


SHOERR y 


Branch to common code 




92 


ERR 4 ♦ 


MOV 


#FDETERyRl 9 


Detach region message 




93 


SHOERR : 


MOV 


♦BUFF y RO y 


Set up for $EDMSG 




94 




MOV 


#*BSWyR2 9 






95 




CALL 


$EDMSG y 


Edit message 




96 




QI0W*S 


#I0»WVBy#5y#ly y 9 9 


<#BUFFyRly#40> 




97 








Display message 




98 




EXIT*S 




Exit 




99 




♦ END 


START 






Run 


Session 









>RUN CREURG 

CREURG HAS CREATED AND INITIALIZED THE REGION 
>RUN ATTURG 

ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB 
ABABABAB121212121212121212121 21212121212121212121212121212121212 
.1.212121212121212121212121212121212121212121212121212121212121212 
1212121212121212121212121212121212121212121212121212121212121212 
1212121212121212 



Example 8-2 Creating a Region and Placing 
Data in It (Sheet 2 of 2) 
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Example 8-3 attaches to the region created by Example 8-2, 
reads and displays the data, and then detaches from the region and 
marks it for delete. The following notes are keyed to Example 

8-3. 

Again, task-build with the WNDWS=1 option so that the Task 
Builder allocates space for the window block in the task 
header . 

Q This example uses all three forms of the directives, for 
illustration purposes. 

Q The RDB for attaching to the region. In fact, the only 
required information is the region name and the region 
status word. The partition name and size, although 
included here, are not needed. RS.MDL set marks the 
region for delete when we do an explicit detach. You need 
delete access to mark the region for delete (RS.DEL). 
Also, attach with read (RS . RED) and write (RS.WRT) access 
so that you can map with read/write access. 

Q The WDB for the virtual address window. We map the entire 
region (length = 100 (8) 32-word blocks) , starting from the 
beginning (offset = 0). WS.MAP means create the address 
window and map. Map with read (WS.RED) and write (WS.WRT) 
access. 

O Attach to the region. 

Q Move the region ID to the WDB; create the virtual address 
window and map it to the region. 

Q Set base address in region - again 160000(8), because the 
base APR is APR 7. 

O The first word in the region contains a character or byte 
count . 

Q Number of characters to print on each line, except the 
last line (if it has less than 64(10) characters). 
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Loop through region, printing 64(10) characters per line. 
This technique is used to demonstrate how to control the 
width of the output and make the run session fit on an 
8-1/2" by 11" page with margins. If the full terminal 
buffer width (typically 80(10) or 132(10)) is acceptable, 
one QIO directive, with the total character count 
specified for number of characters, would be enough to 
write the entire region. In that case, the terminal 
driver will automatically wrap to the next line after a 
full line is displayed. 

Detach from the region. An explicit detach is required to 
mark the region for delete. 

NOTE 

In Chapter 7, we discussed the fact that a 
task needs read/ write access to a region to 
issue QIOs to write directly from a region. 
This also applies to dynamic regions. ATTURG 
issues QIOs directly from MYREG. Therefore, 
although it appears that ATTURG only needs 
read access, it actually needs read/write 
access. See the discussion following Example 
7-1 in Chapter 7 for additonal information. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
[21 
[22 
23 
r24 
25 
26 
27 
28 
L29 
30 
31 
32 
"33 
34 
35 
36 
37 
38 
39 
40 
"41 
42 
43 
"44 
45 
.46 



♦TITLE ATTURG 
♦IDENT /Ol/ 
♦ ENABL LC 



y Enable lower case 



y + 

y File ATTURG*MAC 



Program to attach to an existing region y create a 
virtual address window ( mapped on creation) y read 
ASCII data from the region? detach from the region 
and exit* The region will be deleted on last detach* 
The first word in the region contains a count of how 
many bytes of data are in the resfion 

Assemb 1 e and t ask~bu i 1 d i nst r uc t i ons * 

>MACR0/LIST LB: CI » 1 3 PROGM ACS/LIBRARY* dev J Cuf d 3 ATTURG 
M.INK/MAP/0PTI0N ATTURG y LB * L 1 y 1 3PR0GSUBS/LIBRARY 
>0ption? WNDWS-1 
XJption? <RET> 



rdb: 



WINi 

wdb: 



♦ MCALL 
♦ MCALL 
♦ MCALL 
RDBBK* 

Define 



CRAW* 
WDBBK* 

Define 



EXITfcSy RDBBK* y WDBBK* y ATRG*C 5 System 
CRAU$yDTRG*SyDIR*yQIOW*S y macros 
DIRERRy I'OERR y Supplied macros 
.100 y MYREG y GEN y <RS ♦ MDL ! RS ♦ DEL ! RS ♦ RED ! RS ♦ URT> 
region with* 
Size ™ 100 (32* word blocks) 

Name = MYREG 

Partition = GEN 

Mark for delete on last detach 
Attach with ready write? and delete access 

WDB 5DPB for create address window 

7 y 1 00 y y y 1 00 y <WS ♦ MAP ! WS * RED ! WS ♦ WRT> 
window with* 



APR 
Size 
Offset 
Length 
Map on 



m region ~ 
in region ~ 
create with 



7 

100 (32* word blocks) 
(32* word blocks) 
100 (32* word blocks) 
read and write access 



iosb: .BLKW 
start: atrg*c 

BCS 
MOM 

DIR* 



2 y I/O status block 

RDB y Attach to region 

ERR1 y Check for error 

RDB+R* GIDy WDB+W*NRID y Move region ID 

y into WDB 

#WIN y Create window 



Example 8-3 Attaching to an Existing Region 
and Reading Data From It (Sheet 1 of 2) 
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"Dr*C 
JDLO 


ERR 2 




9 Check "for error 


4Q 
"to 




JvifllJ 

nu v 


#160000 


j-R5 


9 Sot fc>3se 3ddr in rcjsf ion 


49 

*t T 




1 IUV 


<R5)+>R4 


9 G? © *t ch3racter count*/ 


*J \J 




1 IU V 


#64 ♦ » R3 




9 L/i lo 1 b r* fcr 1 J. .L I 1 r« 


ur-i 

w J. 


i nnp i 


GI0W$S 


#I0*WVB 


9 #5 9 #1 9 9 


* J. w O jQ 9 9 •• i\ J " u J ! 11 I \s .• 


52 










9 Writ© d3ta 


53 




BCS 


ERR3D 




9 Check for dir error 


c ;4 
\j *t 




TSTB 


I0SB 




9 Check for 1/0 error 


c-ir 




BLT 


ERR3I 




? Branch on error 


\J o 




SUB 


R3 1 R4 




9 Compute chars left 


>J / 




BLE 


DONE 




9 Branch if done 


58 




ADD 


R3>R5 




9 Point to next char 


59 




CMP 


R3 y R4 




9 Check for < 64 ♦ chars 


60 










9 left to print 


61 




BLE 


LOOP 




9 > or ~9 print next line 


62 




MOV 


R4 r R3 




9 <9 print only that many 


63 










i chsrs 


64 




BR 


LOOP 




9 Print the line 


65 


DONE ♦ 


DTR6*S 


#RDB 




9 Det3ch from region 


66 






ERR 4 




i Check for error 


67 




EXIT$S 








68 


9 Error 


handling code 






69 


ERR1 ♦* 


DIRERR 


<ERR0R 


ATTACHING TO REGIONS- 


70 


ERR2 : 


DIRERR 


<ERR0R 


CREATING 


WINDOW AND MAPPINGS- 


7.1 


ERR3D I 


DIRERR 


<ERR0R 


WRITING 


DATA.?- 


72 


ERR3.T * 


I0ERR 


#I0SBv<ERR0R WRITING DATA> 


73 


ERR4 1 


DIRERR 


<ERR0R 


DETACHING FROM REGI0N> 


74 




♦ END 


START 







Example 8-3 Attaching to an Existing Region 
and Reading Data From It (Sheet 2 of 2) 



364 



DYNAMIC REGIONS 



SEND- AND RECEIVE-BY-REFERENCE 

If you create a private (unnamed) region, you have complete 
control over whether other tasks can have access to it. You 
specifically attach other tasks to the region by sending a packet 
containing a reference to the region. When you do that, you can 
also specify what access they have to the region. At the time, 
you must be attached with at least that much access yourself. 
Named regions, on the other hand, can be attached by any task that 
knows the name and has the access privileges needed to pass the 
protection check. 

Use the Send-by-Ref e rence directive (SREF$) to send a region 
by reference, with the following input parameters. 

Receiver task name 

WDB - Region ID 

offset into region - sent unchecked to receiver 

length to map - sent unchecked to receiver 

window status word - determines how receiving task is 

attached 

address of buffer - 8(10) word buffer which is sent to 
the receiver 

Event flag - if specified, set when the reference is 
received, not when it is queued up (in the receive- 
by-reference queue) . 

The receiver task is attached to the region when the 
reference is queued up. This avoids the problem of the region 
being deleted if the sender exits before the receiver receives the 
region. Remember that private regions are always marked for 
delete on last detach. 

If you are using the event flag for synchronization, note 
that the flag should be used to notify the sender as to when the 
receiver receives the region by reference. It is not the same as 
Send and Receive Data directives, where the flag is set when the 
reference is queued. That flag should be used to notify the 
receiver. 
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The receiver follows a somewhat modified procedure to access 
the region, as follows. 

1. Create window. 

2. After reference is queued, receive by reference (fills in 
reg ion ID in WDB) . 

3. Map to region. 

4. Use region. 

5. Detach from region. 

Use the Receive-by-Reference directive (RREF$) to receive a 
reference to a region, with the following WDB input parameters. 

Window Status Word - WS.MAP for receive and map; WS.RCX for 
receive data or exit. 

Buffer Address - 10(10) word buffer for sender task name (in 
Radix-50 format) and data. 

The following WDB output parameters are returned, all as set 
by the sender: 

Region ID 

Offset into region 

Length to map 

Window status word - describes how attached 

If the WS.MAP bit is set, the Executive maps the window to 
the region, using the offset, length, and window status word 
access as sent. If a separate Map directive is used, the receiver 
can first check and/or modify those parameters before mapping to 
the region. WS.RCX set tells the Executive to exit the task if 
there are no packets in the recei ve-by-ref erence queue. 

Although there are some similarities, Send Data and Receive 
Data are completely independent from Send-by-Ref erence and 
Receive-by-Reference. The receive (data) queue is separate from 
the receive-by-ref erence queue. 

If you want to use ASTs for synchronization, use the Specify 
Receive-by-Reference AST directive (SRRA$) . This causes the 
Executive to transfer control to the specified AST routine when a 
packet is placed in the receive-by-ref erence queue. Generally, 
issue this directive when the task starts up. 
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Examples 8-4 and 8-5 show how to create a pair of tasks, a 
sender task and a receiver task. The sender, Example 8-4, creates 
a private region, initializes it, and sends a reference to it to 
the receiver. The receiver, Example 8-5, in turn receives the 
reference, displays the data, and then exits. One run session is 
included for both examples. The following notes are keyed to 
Example 8-4 . 

This program uses the supplied macro DIRERR to generate 
directive error messages. Therefore, PROGMACS. MLB must be 
specified when assembling, and PROGSUBS.OLB when 
task-bui Id ing . 

O Tne RDB f° r tne region. The name is defaulted to create a 
private region. 

The WDB for the virtual address window. The length 
actually mapped will be returned after mapping. Read 
access is automatic for map, so WS.WRT gets read/write 
access. 

Create and attach to region, create virtual address window 
and map it to the region. 

Use the base virtual address in the window (returned in 
the WDB) to set the base address of the region. Since APR 
7 is the base APR, this address is 160000(8). 

Fill the region with ASCII Ms. 

Send-by-ref erence to RCVREF (Example 8-4) . Event flag 1 
will be set when RCVREF actually does a 
receive- by-reference . 

Display message that a region was created and sent. Then 
wait for event flag 1 to be set. 

Display message saying RCVREF received region, and then 
exit. 

Exit. The Executive will detach you from the region. 
Note that even if SNDREF exits before REVREF receives the 
region by reference, the region will not be deleted 
because RCVREF is attached when the reference is queued. 
The region is deleted only after both SNDREF and RCVREF 
detach . 



367 



DYNAMIC REGIONS 



♦TITLE SNDREF 
♦I DENT /Ol/ 
♦ ENABL LC 

File SNDREF ♦ MAC 



J Eroble lower esse 



SNDREF creates a 64-word (2 block) unnamed region and 
fills it with ASCII' characters* It then sends the 
region -to RCVREFy and then waits for RCVREF to receive 
the region* (This is signalled by event flag #1*) It 
then prints a message and exits* Since the area is 
unnamed y it is automatically deleted when the last 
attached task exits* 

Assemble and task-build instructions I 

>MACRO/LIST LB I C .1. 9 1 3PR0GMACS/LIBRARY 9 dev X Cuf dDSNDREF 
>LINK/MAP/OPTION SNDREF 9 LB* I." 1 9 1 1PR0GSUBS/L IBRARY 
Option? WNDUS-.1. 

Install and run instructions* RCVREF must be installed* 
Run SNDREF first » then run RCVREF* 

♦ MCALL QIOW$C>QIOW*SyRQST*C i System macros 
♦ MCALL UTSE$C » EXI T$S 9 RDBBK* 9 WDBBK* 
* MCALL CRRG*SyCRAW*SySREF*C 



* MCALL DIRERR 
♦ NLIST BEX 



9 Supplied macro 
? SUPPRESS DATA 



Define region with* 

Size = 2 32-WORD BLOCKS 

Name - none 

Partition ~ GEN 

Protection = WO « none rGR* RUED 

OUJRUEDySYtnone 

Attach on create 
9 Read and write access desired on attach 

RPRO = 170017 
RSTAT - RS ♦ ATT ! RS *RED ! RS *URT 



RDBi 



RDBBK* 2 9 9 GEN t RSTAT 9 RPRO 



53 



Define window with* 
APR 
Size 

Offset in regior 
Length to map 



WSTAT 

udb: 



™ 2 32~word blocks 
~ 32- word blocks 

32- word blocks (defaults 
to smaller of region 
size and window length) 
M3P on create with read and write access 
« US* MAP! WS.WRT 

WBBBK* 7 92.9Q9Q9 vUSTAT 



Example 8-4 Send-by-Re f erence (Sheet 1 of 2) 
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54 5 

55 MES1J ♦ ASCII / SNDREF HAS CREATED THE REGION AND HAS/ 

56 ♦ ASCII / SENT IT TO RCVREF ♦ / 

57 LMES1 ™*--MESl 

58 MES2 ♦ ♦ASCII / RCVREF HAS RECEIVED IT* SNDREF IS NOW/ 

59 ♦ ASCII / EXITING ♦ / 

60 LMES2 * . - MES2 

61 *LIST BEX * Show binary extensions 

62 *EVEN 

63 *ENABL LSB ? Enable local symbol 

64 i blocks 

65 START: CRRG*S #RDB * Create and attach to 

66 ? region 

67 BCS 1* r Branch on dir error 

68 MOV RDB+R ♦ GID y WDB+W ♦ NRID 5 Copy region ID 

69 f into WDB 

,70 CRAW*S #WDB ? Create and mar- window 

71 BCS 2* ? Branch on dir error 

72 MOV WDB+W* NBAS yRO i base V*A* of region 

73 t Fill region with all M's 

74 MOV #64*yR3 t count of words to move 

75 20$ X MOV #"MMy<R0)+ > Move in an ASCII M 

76 SOB R3?20$ i Loop through region 

77 y Send the region to RCVREF* EF 1 will be set when 

78 y RCVREF recieves it 

79 SREF*C RCVREF y WDB y 1 9 Send by reference to 

80 t RCVREF 

81 BCS 3* ? Branch on dir error 

82 GI0W*C I0*WVBy5y2y y y y <MES1 y L.MES1 y 40> y Display 

83 y message 

84 BCS 4$ J Branch on dir error 

85 WTSE*C 1 ? Wait for RCVREF to get 

86 y the region 

87 BCS 5$ 9 Branch on dir error 

88 QI0W*C I0*WVBy5y2y y y y <MES2 y LMES2 y 40> y Display 

89 y message 

90 BCS 6$ i Branch on dir error 

91 EXIT$S 9 Exit 

92 y Error code 

93 1$: DIRERR <ERR0R ON CREATE OR ATTACH REGI0N> 

94 2$: DIRERR <ERR0R ON CREATE OR MAP WIND0W> 

95 3$: DIRERR <ERR0R ON SEND BY REFERENCE.:- 

96 4$: DIRERR <ERR0R ON 1ST WRITE> 

97 5$: DIRERR <ERR0R ON WAIT F0R> 

98 6$: DIRERR <ERR0R ON 2ND WRITE> 

99 *END START 



Run Session 



>INS RCVREF 

>SET TERMINAL/WIDTH ♦ 64 ♦ 
>RUN SNDREF 

SNDREF HAS CREATED THE REGION AND HAS SENT IT TO RCVREF* 
RUN RCVREF 

RCVREF HAS RECEIVED IT. SNDREF IS NOW EXITING* 
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM 
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM 
>SET TERMINAL/WIDTH ** 80 * 

Example 8-4 Send-by-Re f erence (Sheet 2 of 2) 
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The receiver, Example 8-5, receives a reference, displays the 
data , then exits. The following notes are keyed to the example. 

Q This program uses the supplied macros DIRERR and IOERR to 
display directive and I/O error messages. 

Q WDB for virtual address window. The size is 200(8) 
32-word blocks, a full 4K words. The offset into the 
region, the length to map, and the access will be filled 
in on receive. Since the length to map sent by SNDREF is 
two blocks, '2' will be used in mapping. Note that the 
window can be more than two blocks long. WS.MAP must be 
left clear until after the window is created. Otherwise, 
the Executive will try to map the window to the region, 
causing an error. See the discussion which follows. 

Q Create the virtual address window. 

Q Set WS.MAP so that the task will map as part of the 
receive-by-ref erence . 

Q Rece ive-by-ref erence and map. 

Q Set base address in region, using base virtual address for 
APR 7 (160000 (8) ) . 

Q Get length actually mapped (two blocks, the same as length 
of region) and convert from blocks to bytes. Just display 
that many characters. 

Q Display all characters with one QIO directive. Note on 
the run session that we set the terminal buffer to 64(10) 
to allow for margins on an 8-1/2" by 11" page. 

Q Exit. The Executive will detach the task from the region. 
When both tasks have detached, the region will be deleted. 

The receiver may map after the receive-by-ref erence or as 
part of the receive-by-ref erence . If the receive-by-ref erence and 
the map are combined in one directive, issue the 
Receive-by-Ref erence directive with the WS.MAP bit set. In that 
case, the WS.MAP bit must be clear when the window is created, 
since you can't map until you receive. This is necessary because 
even though the receiver is attached to the region when the 
reference is queued up, the region ID isn't filled in the WDB 
until the receiver executes the Rece ive-by-Ref erence directive. 
Therefore, if you receive and map in one call, issue the Create 
Address Window directive with the WS.MAP bit clear; then set it 
before issuing the Receive-by-Ref erence directive. If you use a 
separate Map directive, the WS.MAP bit can be left clear. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
"26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
"37 
38 
39 
40 
41 
42 
43 
44 
45 
46 



♦ TITLE: 
. I DENT 
♦ ENABL 



RCVREF 

/Ol/ 

I...C 



$ Enable lower case 



? + 

? Fil< 
y 
? 

y 



RCVREF ♦ MAC 



Program to receive-by- reference a region from SNDREF 
map to the region? read ASCII' data from the region y 
detach from the region and exit* The region will be 
y deleted on last detach* 
y 

9 A s s e in b 1 e a n d t a s k - b u i Id i n s t r u c t i o n s J 
? 
y 
y 
? 
y 
y 
y 



MACRO/LIST LB: CI 1 1 3PR0GMACS/LIBRARY y dev J Cuf dTJ RCVREF 
LINK/MAP/OPTIONS RCVREF y LB* CI y 1 UPROGSUBS/LIBRARY 
Option? WNDWS=1 
Option? <RET> 



Install and run instructions J RCVREF 
Run SNDREF first and then run RCVREF 



iust be installed 



i Defir-H 

y 
y 
y 
y 
y 
y 
y 
y 

y Note? 
WDB J 
y 

rec: 

WIN? 

iosb: 



♦ MCALL EXIT*SyWDBBK*yRREF* 5 External system 
♦ MCALL QIGW*SyCRAW*yDIR* i macros 
♦ MCALL DIRERR y 10 ERR $ External supplied 

y macros 

> window with* 

APR « 7 

Size « 200 (32* word blocks) 

Allow for full APR 
These are filled in on receiver as set by sender* 



Offset in region =~ 
Length in region « 



(32* word blocks) 
(32* word blocks) 
reset when mapped 



Access 







Must map after receiving (or as part of 
WDBBK* 7»200 



receive ) 



RREF* 
CRAW* 
♦ BLKW 



START* DIR* 

BCS 
BIS 



WDB 
WDB 



#WIN 



y Set up DPB for RREF* 
y Set up DPB for CRAW* 
y 1/0 status block 



y Create virtual address 
y window 
ERR1 y Branch on error 

#WS*MAPyWDB+W*NSTS y Set WDB to map on 

y receive 



Example 8-5 Receive-by-Re ference (Sheet 1 of 2) 
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47 
48 
49 
50 
51 
"52 
53 
"54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 



f Error 
ERR1 : 
ERR 2 ♦ 

ERR 3 1 
ERR 4 1 



DIR* 

BCS 
MOV 

MOV 
MUL 

QIOW*S 

BCS 

TSTB 
BLT 

EXIT*S 

code 
DIRERR 
DIRERR 
DIRERR 
10 ERR 
♦ END 



#REC 

ERR2 

#160000yR5 

WDB-fW»NLENyR3 
#64* yR3 



Receive by reference 

3Tld ITI3P 

Branch on error 
Set base address in 

region 
Size of region to R3 
Convert blocks to bytes 



# 1 . W VB 9 #5 t # 1 y t * I OSB t ? <R5 r R3 r #40> 



ERR3 

I OSB 
ERR4 



y Write 
y data 
Branch on directive 

error 
Check for I/O error 
Branch on error 



< ERR OR CREATING VIRTUAL ADDRESS WINDOWS- 
TERROR ON RECEIVE AND MAP> 
<ERR0R ON WRITE QI0> 
#I0SBy<E'RR0R ON WRITE Q I OS- 
STAR T 



Example 8-5 Recei ve-by-Re ference (Sheet 2 of 2) 
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The Mapped Array Area 

If you want to automatically set up a large core resident 
data area, without using a create region directive, you may use 
special techniques to set up an area called a mapped array area. 
Figure 8-3 shows a task using a mapped array area. The Task 
Builder sets things up so that when the task is initially loaded, 
the task region is larger than normal, with the mapped array area 
set aside in memory immediately below the task header. 

The task is automatically attached to the region, since it is 
part of the task region. Therefore, all you have to do is to 
create a virtual address window and map it to the region. The 
area may be any size, as long as the task image and the mapped 
array area fit into the partition. This means that it may be 
larger than 32K words. 

Typically, the virtual address window maps only a portion of 
the region at a time. in Figure 8-3, the virtual address window 
maps 4K words at a time. 

This technique is used to implement virtual arrays in 
FORTRAN. Since the area isn't set aside until the task is loaded 
into memory, any initialization of the area must be performed at 
run time. 

Use the following procedure to create a task which uses the 
mapped array area. 

1. Set up a separate psect in the source code and reserve 
space for the virtual address window (using . BLKB or . BLKW 
statements). Also set up symbols for reference, if 
desired. Do not initialize any locations. 

2. In the code, create a virtual address window. 

3. Map the window to a portion of the region. 

4. Later, map to other portions of the region by modifying 
the offset within the region and reissuing the map 
directive. 
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5. Task-build with the WNDWS and the VSECT options. 

WNDWS=n allocates space in the task header for the 
extra window block 

VSECT= psect- nam e : base : window- length : physical- length 
where 

psect-name = the name of the psect to be used for 
the virtual address window 

base = the base virtual address for the window 
window-length = the length of the window in bytes 

physical-length = the length of the mapped array 
area in 32-word blocks. 

This option sets up virtual addressing for the region 
and specifies the amount of space to be set aside for 
the mapped array area. 
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160000 APR 7 
APR 6 
APR 5 
APR 4 
APR 3 
APR 2 



APR 1 



APR 



VIRTUAL 
MEMORY 



WINDOW 

(4K WORDS) 



TASK 
IMAGE 

(28K WORDS) 



HEADER & STACK 



(T) INITIAL LOAD AND MAP 

(5) TOTAL SPACE INITIALLY 
ALLOCATED. 4K WORD 
AREAS MAPPED AS 
NEEDED. 




PHYSICAL 
MEMORY 



TASK 
IMAGE 



HEADER & STACK 



MAPPED 

ARRAY 

AREA 

(32K WORDS) 



Figure 8-3 The Mapped Array Area 
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Example 8-6 shows how to create and use a mapped array area. 
The following notes are keyed to the example. 

Q This program uses the supplied macro DIRERR. 

Q WNDWS = 1 is needed to reserve space for the extra window 
block. The VSECT option sets up addressing for Psect W, 
beginning at virtual address 160000(8), for a length of 
20000(8) bytes or 4K words. The last argument sets up a 
mapped array area 2000 32-word blocks = 200000(8) bytes 
long = 32K words. 

Set up Psect W, which is used for mapping the mapped 
array area. Symbol A marks the beginning of the window at 
virtual address 160000(8). The number of bytes reserved 
must be at least as long as the window size (4K words) . 

Q Data to be placed in the mapped array area. 

WDB for the window. The region ID is left '0' because the 
region is the task region, which always has region ID 0. 

Q Create the virtual address window and map starting at 
offset 0, to the first 4K word area. 

Q Move "A1G7" into the first two words of the area. 

O Modify the offset in the region in the WDB (at offset 
W.NOFF) to 200(8) blocks, so that mapping will begin at 
that offset within the region. 

Q Map to the second 4K word area. 

Q Move "B2G7" into the first two words of the second 4K word 
area . 

Q Similarly, map and move "C3G7" to the third 4K word area, 
and "D4G7" to the fourth 4K word area. 

Q Map back to the first 4K word area. 

Display the first four bytes. 

© Map to the second 4K word area and display the first four 
bytes. 
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© Map to the fourth 4K word area and display the first four 
bytes . 

® Map to the third 4K word area and display the first four 
bytes. 

The mapping order for displaying the data is different just 
to show that the order need not match the original order for 
placing the data into the region. 

Now do the Tests/Exercises for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either the on-line files 
(which should be under UFD [202,2]) or the printed copies in the 
Tests/Exercises book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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O 

e 



e 

e 



©[ 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
! 14 
15 
16 
17 
18 
19 
20 
21 



1-24 
25 
r26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 



♦TITLE 
♦I DENT 
♦ ENABI... 



US 3 
/0.1V 

I...C 



y Enable lower case 



y This program uses the mapped array area* It places 

v data in the first 2 words of each of the first four 

y 4K word blocks* It then retrieves the data and prints 

y i t a t t h e t e r m i n a 1 ♦ 
y 

P Ass e m b 1 e a n d t a s k - b u :i 1 d i n s t r u c t i o n s ♦ 



MACRO/LI 

LINK/MAI" 

Option? 

Option? 

Option? 

♦MCALL 

♦ MCALL 
.PSECT 



S T L B * C 1 y 1 .'.I P ROGMACS/ 1... .1 B R A R Y y d e v t C u f d 3 V S 3 

/OPT I ONS VS3 y PROGSUBS/L I BR AR Y 

WNBWS«1 

VSECT^VV * 1 60000 1 20000 1 2000 
<RET> 



Q 1 0W*S y EX I T*S t WDBBK* r CR A W*S t M AP*S 

y S w s t e iti m a c r o s 
y 
y 



DIRERR 

VV CONyGBL 



a: 



♦ BLKB 20000 



DATA ♦ 
DATB * 
DATC ♦ 
DATDJ 
DATGJ 
y Define window 

wdb ♦ wdbbk* 
start: craw*s 



♦PSECT 
♦ASCII 

♦ASCII 
♦ASCII 
♦ASCII 
♦ASCII 



S u p p 1 i e d m a c r o 
Psect for ffiBP^ed array 
area 

Used to reference the 

virtual area 
Back to blank Psect 



/Al/ 
/B2/ 
/C3/ 
/D4/ 
/G7/ 

d e f i n i t i o i"i b 1 o c k 
7y200y0y0y200y<WS 
#WDB ? 



Al 



A4i 



BCC 

DIRERR 

MOM 

MOV 

MOV 

MOV 

MOV 

MAP$S 

BCC 

DIRERR 

MOV 

MOV 



MAP! WS\WRT>yO 
y C r e a t e w i n d o w 
y to 1st 4KW block 
? Branch on dir ok 
CREATING WINDOW OR ON FIRST 
data to 1st 



Al 

<ERR0R 

DATA y A ? 
#2 y R5 

DATGy A( R5) 9 
#WDByR0 

#200yW*N0FF(R0) 9 
#WDB 9 
A4 y 
<ERR0R ON 1ST MAP 
DATB y A 
DATGy A<R5) 



and map 



map: 

wor-i 



Move 

Move data to 2nd word 

Set up next 4KW block 
Map 2nd 4KW block 
Branch on dir ok 
TO 2ND 4KW BL0CK> 



Example 8-6 Use of the Mapped Array Area (Sheet 1 of 2) 
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A7 




MOM 


44nn uU. wru-P" ( ftn 1 s 


%.> fer Cr U r> t!> 1 *t t\ U J. IJ U r*. 




48 




MAP$S 


#UDB 

IT W JU* JU* 






49 




BCC 


A7 






•^ft 




fl T ft 1- ft ft 
JU .L Ia C r\ l\ 


Pftftflft flM 1 <3T MAP 


1 U 0. 1 \ JLJ *t 1 \ W Ju» L. U w \\ .'' 






A7 ♦ 

H / ♦ 


1 lUv 


JL'ri 1 l./ y rl 




© 






MflU 

IIUv 


A.'rl 1 u 9 M \ r\\J y 






\J W 




MflU 


touuf wtiiui r \ nu / y 


v.) fcv 1/ *.J r' * w! i *t l\ L* J. \J u. r*. 




54 




MAP**? 

1 i r 1 1 *k w 


#UDB 

IT W JL 1 A. 1 










BCC 


A8 






56 




DIRERR 


<ERR0R ON 1ST MAP 


TO 4TH 4KW BLOCK..'- 




57 


as: 


MOV 


DATDmA 






.58 




MOV 


DATGy A(R5) 






"59 




MOV 


t-0 9 W*NGFF<R0) 9 


Go back to 1st, 4K block 


© 


60 




MAP*S 


#WDB 






61 




BCC 


A9 9 


B r a n c h o n d .1 r o k 


© 


62 




DIRERR 


<ERR0R ON 2ND MAP 


TO 1ST 4KUI BLOCIO- 


63 


A9; 


QI0U4S 


# 1 ♦ W VB 9 #5 9 # 1 9 9 9 9 


;#Ay#4y#40> 


"64 




MOV 


#200»W*N0FF(R0) 9 


Go to 2nd 4K block 


© 


65 




MAP*S 


#WDB 




66 




BCC 


AIO 9 


B r a n c h o n d i r o k 


67 




DIRERR 


<ERR0R ON 2ND MAP 


TO 2ND 4KW BLOCIO- 




-68 


aio: 


QI0W*S 


#I0.WVB»#5»#1 9999< 


:#Ay#4y#40> 




- £9 




MOV 


#600 » LI * NOFF ( RO ) J 


Rn in 4th 4K hi nrk 


© 


70 




MAP*S 


#WDB 




71 




BCC 


All 9 


B r a n c h o n d :i. r o k 


72 




DIRERR 


<ERR0R ON 2ND MAP 


TO 4TH 4KW BLOCIO 






All* 


UlUWfa 


# .1. U ♦ W VB 9 #;.) 9 *1 9 9 9 9 - 






■74 




MOV 


#400»U*N0FF(R0) ? 


Go to 3rd 4K block 


© 


75 




MAP*S 


#WDB 




76 




BCC 


A12 9 


Branch on d:i. r ok 


77 




DIRERR 


<ERR0R ON 2ND MAP 


TO 3RD 4KW BLOCIO 




-78 


A12J 


QI0W*S 


#I0.WVBl>#5Vfrl 9 9 9 9 < 


:#Ay#4y#40> 




79 




EXIT*S 


9 


Exit 




80 




♦ END 


START 






Run 


Session 










>RUN 


VS3 









A1G7 
B2G7 
D4G7 
C3G7 



Example 8-6 Use of the Mapped Array Area (Sheet 2 of 2) 
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INTRODUCTION 

The RSX-11M file system is composed of three parts. 

• File structures - the organization and data structures 
maintained on the mass storage volumes themselves 

• Ancillary Control Processors (ACPs) - tasks which maintain 
the file structures and provide access to them 

• File access routines - provide user-written tasks with an 
interface to ACPs, which provide and maintain organization 
within files. 

This module reviews some basic information about file 
storage, and provides general information about the RSX-11M 
primary file structure called FILES-11, and its ACP. This module 
also presents an overview and comparison of the two supplied file 
access subsystems, File Control Services (FCS) and Record 
Management Services (RMS). The following module provides details 
on programming using FCS, which is the more widely used subsystem. 



OBJECTIVES 

1. To describe the steps involved in file I/O 

2. To describe the FILES-11 structure and how the F11ACP 
maintains that structure during file I/O 

3. To identify the advantages of using either FCS or RMS for 
file access. 



RESOURCES 

1. IAS/RSX-11 I/O Operations Reference Manual , Chapters 1 and 
5 

2. RMS-11 user's Guide 
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OVERVIEW 

Quite often in an application you need to store data on a 
peripheral device (disk, magtape, etc.) for later retrieval. To 
write such an application, you must know something about the 
different devices which are on your system. In addition, you must 
understand the file structure and its support systems. Once you 
know that, you can learn the procedure for actually performing I/O 
operations. 

TYPES OF DEVICES 
Record-Oriented Devices 

Record-oriented devices have the following characteristics. 

• Data is handled a record at a time. 

• There is no file structure. 

Terminals, line printers, and card readers are all 
record-oriented devices. They are not designed for storage and 
fast retrieval of data, but are designed instead to support 
interactive sessions or provide hard copies of reports and other 
data . 



File-Structured Devices 

File-structured devices have the following general 
characteristics. The data they contain: 

• Can be handled in files 

• Can be stored and retrieved quickly 

• Is typically stored on a storage medium which can be moved 
from one device to another. 

Hard disks, floppy disks, and magtape are examples of 
file-structured devices. The following definitions should prove 
helpful in our discussion. 

a file - a collection of related data; therefore, a 
logical unit of mass storage. 
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volume - a physical unit of mass storage consisting of a 
recording medium and its packaging. Examples are a disk 
pack, a reel of tape, a diskette, and a DECtape II 
cartridge. 

Types of File-Structured Devices - There are two types of 
file-structures devices, sequential and random-access. The type 
is determined by the kind of access to data on it. 

Sequential devices have the following characteristics. 

• Data is retrieved in the same order as written 

• New data is always appended at the logical end of the 
tape, after the last data written 

• data cannot be written in the middle of the volume without 
losing the data past that point. 

Magtape and cassettes are examples of sequential devices. In 
essence, data is stored in order as written. To access any data, 
all data before it on the tape must be read first. 

Under RSX-11M, the magtape ancillary control processor 
( MTAACP) supports the ANSI file structure. 

The MTAACP supports the following file setups: 

• A single file on a single volume 

• A single file on multiple volumes 

• Multiple files on a single volume 

• Multiple files on multiple volumes 

Random-access devices, also called block-structured devices 
or block-replaceable devices, have the following characteristics. 
They can: 

• Store and retrieve data in units called blocks 

• Write or read blocks in any order 

• Rewrite blocks without interfering with other blocks. 

Hard disks (RL01/02, RP06, RM02/03) , diskettes (RX11, RX211) 
and DECtape II are examples of random-access devices. 



386 



FILE I/O 



The FILES-11 file structure, the standard RSX file structure, 
is supported by the FILES-11 ancillary control processor (F11ACP). 
F11ACP supports multiple files on a volume, but a file may not 
extend across volumes. The COPY command (PIP in MCR) maintains 
the FILES-11 structure during transfers of files within a given 
device and between FILES-11 devices on a system. 

The ANSI file structure is useful for transfers of files 
between different (possibly non-DIGITAL) systems. FILES-11 is 
useful between DIGITAL systems under RSX-11M, RSX-1 1M-PLUS , IAS 
and VMS if the two systems have a device in common (e.g., both 
systems have RL02s) . The FLX utility is provided to facilitate 
transfers between RSX and other DIGITAL systems which don' t 
support FILES-11, or between systems which support FILES-11 (even 
between two RSX-1 1M systems) which do not have a common FILES-11 
device. In that case, the FLX transfer is typically made on 
magtape, using DOS or RT-11 format. 
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COMMON CONCEPTS OF FILE I/O 
Common Operations 

File I/O is often used to perform the following operations. 

• Creating a file 

• Deleting a file 

• Modifying existing data within a file 

• Appending new data to a file (or extending the file) . 

Steps of File I/O 

Use the following three basic steps to do file I/O. 

1. Open the file. 

Specify a LUN and the file. The ACP connects a task 
LUN to the file. Specify the access rights desired. 
The ACP checks against the file protection code. If 
you are creating a new file, specify the file 
characteristics (e.g., format and initial length). 

2. Perform the I/O operations. 

Use macros to invoke subroutines to store data in the 
file and/or retrieve data from the file. 

3. Close the file. 

Notify the system that the file operations are 
completed, so that appropriate cleanup work can be 
performed . 
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FILES- 11 

In order to use FILES-11, you need to understand its 
structure and how to interact with it. 



FILES-11 Structure 

A block is the smallest unit of storage which is read from, 
or written to, a FILES-11 device. Typically, the blocks are 
256 (10) words or 512(10) bytes long. Some devices divide or 
format their volumes into pieces which are 256(10) words long, and 
others do not. Therefore, the FILES-11 structure does some 
converting or mapping so that you work with logical blocks which 
are all standard size. When the volume is formatted, logical 
block numbers are assigned to each 256(10) word area on the disk, 
starting with logical block 0. Generally, the position of data on 
a FILES-11 volume can be described in three alternate ways, by: 

• Physical location 

• Logical block number 

• Virtual block number 

Table 9-1 compares the three ways. Figure 9-1 shows an 
example of the mapping among the different methods. Typically, 
you will reference data only within files. The files are 
referenced by virtual block numbers within the file, starting with 
1. Logical block numbers are assigned to the entire disk, 
starting from 0. 

The system converts virtual block number references to 
logical block number references. For example, if you request a 
read of virtual block 5, the system looks at the mapping and finds 
that this corresponds to logical block 1622 (8). This logical 
block, in turn, is mapped to one or more specific sectors on the 
disk, which are read from the disk. 



389 



FILE I/O 



Table 9-1 Comparison of Physical, Logical and virtual Blocks 



Type of Block 
Designation 

Phys ical 



Si ze 

Depends on 
dev ice 



How Designated 

On multi-platter disks, 
designated by cylinder, track 
and sector 



Log ical 



Vi rtual 



256 (10) 
words 



256 (10) 
words 



Numbered in increments relative 
to the beginning of the volume, 
starting with 

Numbered in increments relative 
to the beginning of a file, 
starting with 1 



Typically, data is accessed as records, units which are not 
exactly one block or 512(10) bytes long. A record is a unit of 
user specified size, corresponding, for example, to a single bank 
account or a single line of text at a terminal. 

Figure 9-2 shows how the operating system handles a request 
to read a record using FCS. The first row shows a FORTRAN READ. 
The FORTRAN READ instruction is converted by the compiler to a 
GET$ call to the File Control Services (FCS) to read that record, 
in MACRO, you will issue the GET$ call yourself. FCS checks to 
find out which virtual block within the file contains that record 
and issues the QIO directive for you. The Executive converts the 
virtual block number to its corresponding logical block number and 
issues a read logical block QIO. The driver then converts the 
logical block number to the appropriate physical locations, and 
reads a block of data into memory. The record itself will then be 
located within the block of data. 

The second row shows a BASIC-PLUS-2 READ under the Record 
Management Services (RMS). The BASIC-PLUS-2 compiler converts the 
READ to a RMS $GET call. 'RMS converts this to a QIO, to read the 
corresponding virtual block. From that point on, the steps are 
just like those in the FORTRAN example. 
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file SAMPLE.TXT; 1 



VIRTUAL 
BLOCK #'S 
(IN THE 
FILE) 



LOGICAL 
BLOCK 
#'S (ON 



THE VOLUME) \ 



1 


2 


3 


4 


5 


6 


7 


10 



PHYSICAL 
LOCATIONS 
(ON THE 
VOLUME) 




NOTE: BLOCK NUMBERS ARE IN OCTAL 



Figure 9-1 Example of Virtual Block to Logical Block, 
to Physical Location Mapping 
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FORTRAN 



MACRO-11 

ENTERS HERE 



FORTRAN RECORD 



BASIC-PLUS-2 



FCS RECORD 



• 
• 




• 




• 




• 






• 




• 
• 




• 
• 


EXEC 


• 
• 






READ (5,10) 


COMPILER 


GET$ 

• 


FCS 


QIO IO.RVB. 

• 


F11ACP fc 


QIO IO.RLB 

• 


DRIVER 




1DATA 












• 
• 
• 




• 
• 




• 
• 




• 
• 


TRANSFER 



• 




• 


• 




• 


• 




• 


READ DATA 


COMPILER 


$GET 




• 




• 


• 




• 


• 




• 




VIRTUAL 
BLOCK # 



BASIC-PLUS-2 
RECORD 



RMS RECORD 



LOGICAL 
BLOCK # 



FROM PHYSICAL 
LOCATIONS ON 
DISK 



Figure 9-2 How the Operating System Converts Between 
Virtual, Logical, and Physical Blocks 



Figure 9-3 shows the FILES-11 structures which are used to 
support virtual- to-log ical block mapping. Every FILES-11 volume 
has a number of system files on it, one of which is the Index File 
(INDEXF.SYS) . The Index File contains certain blocks which are 
for system use, plus a file header block for each file on the 
vol urn e . 

Each file header block contains file retrieval pointers which 
are used in mapping virtual blocks to logical blocks. 'Each file 
retrieval pointer locates a range of contiguous logical blocks. 
The first byte tells how many contiguous blocks are in the group, 
and the next three bytes specify the logical block number of the 
first block in the group. Therefore, in the figure, there are 
five contiguous blocks, starting with logical block 336851(10). 
Virtual block 1 = logical block 336851(10), vb 2 = lb 336852(10), 
vb 3 = lb 336853(10), vb4 = lb 336854(10), and vb 5 = lb 
336855(10). The next group of blocks, starting with virtual block 
6 has 51(10) blocks and begins at logical block 336900(10) up 
through logical block 336950(10). The last 17(10) virtual blocks 
(virtual blocks 57(10) to 73(10)) begin at logical block 
337006(10) up through logical block 337022(10). These file 
retrieval pointers are updated each time a change in block 
allocation occurs as a result of a file I/O operation. 
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VOLUME 



maw 



INDEX FILE 



VBN 



FILE 
HDR 



FILE 
HDR 









\ 


FILE 


FILE 


• • • 


FILE 


HDR 


HDR 




HDR 


7 


\ 10 
\ 

\ 




N 



/ 



6 
/ 

/ \ 



/ 



\ 



\ 



FILE HEADER 
FILE 3 



/ 

/ 

/ 


\ 
\ 

\ 

\ 

\ 


SIZE 




1ST 


LBN 



SIZE 
5. 
51. 
17. 



RETRIEVAL POINTERS 



1ST LBN 
H:005 L:021723 = 336851. 
H-.005 L: 022004 = 336900. 
H:005 L: 022 156 = 337006. 



Figure 9-3 FILES-11 Structures Used to Support 
Vi rtual-to-Log ical Block Mapping 
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Directories 

The operating system identifies files by file IDs, which are 
used to calculate the location of the file header within the index 
file. When you need to locate a file, it is difficult to remember 
where it is on the disk, or even what its file ID is. Instead, 
you use a file specification, a more English-like way of 
identifying a file. An example of a file specification is: 
DR1: [5, 6] SAMPLE. TXT; 1. Tasks you write also usually identify 
files with a file specification. Directories are structures set 
up on a FILES-11 volume that are used to group files together, and 
to convert file specifications to file IDs. 

A directory is a list of files belonging to a single user, or 
grouped together for other organizational purposes. An example of 
files grouped together for organization is the libraries in User 
File Directory (UFD) [1,1] on the system device. On a FILES-11 
volume, a directory is a special file containing a list of the 
files belonging to that user or group. For each file, the list 
has : 

• The file specification: name, type, and version number 

• The file ID 

The file ID consists of a file number and a sequence number. 
The file number identifies the offset within the index file to the 
virtual block containing the file's file header. The sequence 
number is used to distinguish this file from previously deleted 
files which used the same file header. There are two levels of 
directories on a volume, as follows. 

• One Master File Directory (MFD) which is directory [0,0] 

• One or more User File Directories (UFDs) 

Figure 9-4 shows the relationship between the two levels and 
the files. The MFD contains a list of the system file, plus one 
entry for each UFD on the volume. Each UFD file has a name of the 
form gggmmm.DIR, where [ggg,mmm] is the user identification code 
(UIC) of the owner. Each UFD contains a list of the files in that 
directory. 
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MFD 
[0,0] 





HIYA.MAC;1 



FLY.TXT;1 



IZZY.TXT;1 



OZY.TXT;1 



LOGIN.CMD;1 



Figure 9-4 Directory and File Organization on a Volume 



Figure 9-5 shows the steps used in locating and accessing the 
blocks of the file DR2 : [ 5 , 6] SAMPLE . TXT ; 1 . The device name, DR1: 
tells which device or volume to look on. The operating system 
reads the MFD file header to find the retrieval pointers for the 
MFD file itself. it converts the virtual blocks to logical blocks 
and reads the blocks of the MFD file. It searches through the 
directory list for the UFD [5,6], namely the file 005006. DIR. 

When it finds that name in the list, it uses the file ID to 
locate the UFD file header. It reads the retrieval pointers 
there, converts the virtual blocks to logical blocks, and reads 
the blocks of directory [5,6]. It looks for an entry 
SAMPLE. TXT; 1 . When it finds that entry, it uses the file ID to 
locate the SAMPLE. TXTs file header. It then reads the retrieval 
pointers in the file header, converts' the virtual blocks to 
logical blocks, and reads the blocks of the file itself. 

If this sounds like a lot of work, it is. Later, you will 
learn about a way to go directly to the file header using the file 
ID if it is opened a second time during a task's execution. 
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DR 1 :[5,6]SAMPLE.TXT; 1 



MFD 
HEADER 



RETRIEVAL 
POINTERS 



• 






• 






• 






005005.DIR 


FILE 


ID 


005006.DIR 


FILE 


ID 


• 



















MFD 



UFD 

HEADER 



RETRIEVAL 
POINTERS 



SAMPLE.TXT;! FILE ID 



UFD [5,6] 



FILE 
HEADER 



RETRIEVAL 
POINTERS 



THIS IS A SAMPLE FILE 



FILE 

SAMPLE.TXT;1 



Figure 9-5 Locating a File on a FILES-11 Volume 
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Five Basic System Files 

There are five basic system files found on all FILES-11 
volumes. They are all created when the volume is initialized and 
are all entered in the MFD. Two of these, the Index File and the 
Master File Directory, have been mentioned previously. The five 
files and their purposes are as follows. 

• The Index File: INDEXF.SYS. 

Boot block - used when a system volume is bootstrapped 

Home block - contains volume identification and other 
info rmation 

Index file bitmap - a record of which header blocks 
are in use; used by F11ACP when allocating header 
blocks to files 

- File header blocks for all files on the volume 

• The Storage Map: BITMAP. SYS. 

A record of which blocks on the volume are in use 
Used by F11ACP when allocating blocks to files 

• The Bad Block File: BADBLK . SYS . 

A list of blocks on the volume known to be bad 

• The Master File Directory: 000000. DIR. 

Entries for the five system files 
An entry for each UFD file 

• The System Checkpoint File: CORIMG.SYS. 

Space used for checkpointing if the system manager 
allocates space in it. 
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Functions of the ACP 

The F11ACP maintains the FILES-11 structure on a volume 
during its use. 

The most elementary functions performed by the ACP are as 
follows . 

• Maintaining the File Header Blocks. This includes: 

Allocating and initializing a file header when a file 
is created 

Recovering a file header for reuse when a file is 
deleted 

- Maintaining file attributes such as protection code, 
length, etc. 

Maintaining the file retrieval pointers 

• Maintaining directories. This includes: 

Creating directory entries when a file or UFD is 
created, or when a file synonym is created (e.g., by 
the PIP /EN switch) 

Removing entries from directories when a file is 
deleted or a file synonym is removed (e.g., by the PIP 
/RM switch) 

• Maintaining block allocation. This includes: 

Allocating blocks to files when a file is created or 
ex tended 

Recovering blocks for reuse when a file is deleted or 
tr uncated 

• Controlling and facilitating task access to files. This 
includes: 

Checking protection codes to determine access rights 

Connecting a task's LUN to a file to allow virtual 
block I/O 

Controlling shared access to files. 
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Figure 9-6 shows the flow of control during the processing of 
an I/O request. This figure parallels Figure 9-2, which shows how 
the operating system converts virtual blocks to logical blocks to 
physical locations. 

The user task issues a read record request which is converted 
by an FCS routine in the user task to a QIO, to read a virtual 
block. The Executive converts the virtual block number to a 
logical block number, using file retrieval pointers in pool. 
These retrieval pointers are built by F11ACP from the retrieval 
pointers in the file header. The Executive issues a read logical 
block request to the driver. The driver converts the logical 
block number to the actual physical locations and copies the block 
into the user buffer. 

For additional information on the FILES-11 structure, see 
Chapter 5 of the IAS/RSX-11 I/O Operations Reference Manual. 




Figure 9-6 Flow of Control During the Processing of an 

I/O Request 
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OVERVIEW AND COMPARISON OF FCS AND RMS 
Common Functions 

The File Control Services (FCS) and the Record Management 
Services (RMS) both offer easy methods for performing file I/O. 
The operator or programmer need not be concerned with all the 
nitty-gritty details, but can instead let FCS or RMS take care of 
them. Both perform the following functions: 

• Serve as an interface to the ACPs 

• Allow I/O to the virtual blocks of a file on a 
block-by-block basis (Block I/O) 

• Divide files into logical records and allow I/O to 
individual records within a file (Record I/O) 

• Allow the programmer to process records using one of the 
following buffers (Figure 9-7) 

A buffer reserved by the programmer with another 
buffer transparently used by FCS or RMS (move mode) 

Directly in the buffer used by FCS or RMS (locate 
mode) 

• Allow device independent I/O - the routines are written to 
work correctly with terminals, disks, etc. 

• Provide mechanisms for controlling shared access to files. 

Beyond that, FCS and RMS each offer a variety of file 
organizations, record types, and access modes. These are 
described in the following sections. 
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MOVE MODE 



TASK 

(IN MEMORY) 



DISK 




MOVE BLOCK 
TO INTERNAL 
BUFFER 

(IF NECESSARY) 



ABC 



MOVE RECORD 
TO USER 
RECORD BUFFER 

















ABC* 


• • 













USER RECORD 
BUFFER 



INTERNAL 
BUFFER 



LOCATE MODE 



TASK 

(IN MEMORY) 



DISK 




MOVE BLOCK 
TO INTERNAL 
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POINTER 
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/ 
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/ 










| ABC • • • 













INTERNAL 
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Figure 9-7 Move Mode and Locate Mode 
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FCS FEATURES 



File Organizations 

Essentially, all FCS supported files are sequential, meaning 
that new records are added at the end of the file, and records are 
stored in the order they are written. Figure 9-8 shows a file 
with sequential organization. 



END OF FILE 

v 



RECORD 


RECORD 


RECORD 


• • • 


RECORD 


1 


2 


3 




n 



SEQUENTIAL FILE ORGANIZATION 
Figure 9-8 Sequential Files 



Supported Record Types 

FCS supports two record types, fixed-length records and 
variable-length records. Variable-length records may be sequenced 
or nonsequenced . An example of each type of file is shown below 
with the following three records: 

12345 

123 1234 

AAAA BBBB CC D 

The examples are in DMP format; the six-digit number on the 
left is the byte count in octal of the first byte in that row. 
Then 16(10) = 20(8) bytes follow in order in octal. Below each 
byte in octal is its equivalent in ASCII. An underscore (_) 
stands for an ASCII blank. Consult the examples as you read the 
description of each record type which follows. 
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Ex am pi e s : 

Fixed-Length Records (record length = 17(10)) 
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Fixed-length records all contain the same number of bytes. 
Therefore, the location of the beginning of any record within the 
file can be computed from its record number. With all record 
types, each record begins on an even word boundary. This means 
that in files with fixed-length records, if each record contains 
an even number of bytes, the next record begins immediately after 
it. If, on the other hand, each record contains an odd number of 
bytes, one byte is unused after each record, and the next record 
begins at the next word boundary. This unused byte is called a 
pad byte. 

Variable-length records may each have different lengths. For 
all files with variable-length records, the first word of each 
record contains a byte count, telling how many bytes are in that 
record. For variable-length nonsequenced records, this count word 
is followed by the data itself. 

Following this, at the next word boundary, is the byte count 
for the next record and then its data. To locate a given record 
within the file, you must first read the byte count for the first 
record in the file. You can then use the byte count to locate the 
second record. You then continue reading byte counts and locating 
successive records until you reach the desired record. 

Variable-length sequenced records contain a byte count, a 
user specified sequence word, and then the data itself. The 
sequence word can contain the record number or any other user 
specified value. Va ri able- leng th sequenced records are not used 
much under FCS. They are supported to allow compatibility with 
RMS var iable-with-f ixed-control records. 
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Table 9-3 compares the different FCS record types. 



Table 9-3 Comparison of FCS Record Types 



Record 
Type 

Fixed-Leng th 



Characteristics 

Record length 
set when file 
created 



Overhead 
in File 

None 



Common 

Appl icat ions 

Files with similar 
data in each record 



Variable-Leng th 
( nonsequenced ) 



Variable- length 
( sequenced ) 



Records all same 
length (shorter 
records padded) 

Records may be 
of different 
leng ths 

First word of 
each record is 
a byte count 

Variable length 
records, with an 
additional word 
for a user speci- 
fied sequence 
n urn be r 



On e wo r d pe r 
record (holding 
record length) 



Two wo r d s pe r 
record (one for 
record length, 
one for sequence 
field) 



Bank account infor- 
mation, bad credit 
card lists, etc. 

Files with varying 
contents among 
record s 

Files to be printed 
Source and list files 



infrequently used, 
except for compati- 
bility with RMS 
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Record Access Modes 

FCS offers two record access modes, sequential access and 
random access. Table 9-4 compares the two access modes. The 
major difference is that with random access, the user can process 
records in any order (e.g., record 12, then record 4, then record 
29) . This is possible with fixed length records only, because FCS 
can calculate the position of each record within the file from the 
record number and the record size. 

With variable-length records, on the other hand, FCS can't 
locate record 12 unless it reads records 1 through 11 first, using 
the record length in the first word of each record to calculate 
the starting position of the next record. Therefore, you must use 
sequential access with variable length records. You may choose 
either of the two access modes for fixed length records, depending 
on how your application processes the records. 
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Table 9-4 



Characteristics 

Devices supporting 
this type of access 

Record types using 
this type of I/O 

Sequence of records 
in the file 



Order of processing 
records 



Comparison of Sequential Access I/O and 
Random Access I/O 



Sequential 
All devices 

All record types 



Determined by the 
order in which they 
are written to the 

Usually the same 
order as in the 
file (one after 
another) 



Random Access 

Block-str uctured 
devices only 

Fixed-length 
records only 

Usually determined 
by the order in 
which they are 
written to the file 

In any order , as 
specified by the 
user (using the 
record number) 



Overhead if records 
are processed in 
same order as they 
are stored in the 

Overhead involved 
if records are 
processed in 
order different 
from how they are 
stored in the file 



Low 



Much higher than 
random access I/O 



Low, but not as 
low as sequential 



Much lower than 
sequential I/O 



With sequential access, special system 
subroutines allow the user to save pointers 
to a record for much faster subsequent 

lllilll^^ 
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File Sharing 

A task which opens a file may choose one of the following 
options : 

• That no other accessor change any data in the file while 
it has access ("shared" read, "exclusive" write) . 

If this task desires read access, other accessors may 
have simultaneous read access, but no other accessor 
may have simultaneous write access. 

If this task desires write access, no other accessor 
may have simultaneous read or write access. 

- Any access request causing a conflict is rejected. 

• That other accessors may change the data while it has 
access ("shared" read/write access). 

If this task requests read or write access, other 
accessors may have simultaneous read or write access. 

Use extreme care - Any precautions against corrupted 
data are the responsibility of the accessors. 

• That no other accessor changes any block within the file 
which has already been accessed (block locking) . Shared 
access to the file is allowed, but: 

Each block which is written to is locked for exclusive 
write access. 

Each block which is read is locked for shared read 
access . 

It is not recommended if accessing a large numbers of 
blocks, because each block lock uses four words of 
pool . 

Any attempt to access a block which causes a conflict, 
returns an error. 
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RMS FEATURES 



File Organizations 

RMS supports three file organizations, sequential, relative 
and indexed. See Figure 9-9. Sequential files under RMS are the 
same as sequential files under FCS. A relative file is composed 
of a series of cells of uniform size. The cell size is greater 
than or equal to the largest record to be placed in the file. A 
single record may be written to a cell, or the cell can be empty. 
The cells may contain variable-length records. Variable-length 
records within relative files can be accessed randomly because 
each record is contained within a fixed-length cell. Also, when 
you read successive records in a relative file, empty records are 
automatically skipped. 

An indexed file is composed of records, plus one or more 
indexes which are used to access those records. Each index is 
used to retrieve records according to the contents of a particular 
field, or key, within the record. The data records themselves are 
ordered according to a primary key which you declare when you 
create the file. 

Figure 9-9 shows an indexed file with a single key, namely 
last name. in the example, the data records are in the bottom 
row, ordered alphabetically by last name. The index for this file 
contains two other levels, level 1 and level 2 (the root level) . 

A search for a record begins at the root level. For example, 
to find the record with key value FRANCIS, search through the root 
level, checking for the first value which is greater than or equal 
to FRANCIS. The first such value is SMITH. Go to the next level 
and again search for the first value greater than or equal to 
FRANCIS; it is GROSS, the first value. Now go to the next level 
and search again; this time the value FRANCIS is found. Since 
this is level 0, we have found the record. 

As new records are added to the file, they are inserted in 
order at level of the primary index. The primary index 
structure is adjusted for the new entry at the same time. In 
addition, any alternate index structures for other keys are 
adjusted as well. There is always one primary key, and there may 
be as many as 254 (10) alternate keys. 
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END OF FILE 



RECORD 


RECORD 


RECORD 




RECORD 


1 


2 


3 




n 



SEQUENTIAL FILE ORGANIZATION 



RECORD 
1 



RECORD gEMPTY? RECORD /? EMPTY J; . . , 



RECORD 



RELATIVE FILE ORGANIZATION 



LEVEL 2 
(ROOT) 



high key 



ANDREWS DAVIS 



GROSS 



MORRIS 



THOMAS high key 



LEVEL 



ADAMS 
10246 









ANDREWS 
50406 


BAKER 
11022 















i 


DAVIS 
02139 


EDSON 
01142 




FRANCIS 
46423 




GROSS 
54966 


HARRIS 
11462 













INDEXED FILE ORGANIZATION 



WELLS 
43168 



Figure 9-9 RMS File Organizations 



Level of the alternate keys contains pointers to the 
original location of the data record itself. If a data record is 
ever moved in order to maintain the index structure, a pointer is 
created and maintained in the records original location, which 
points the data record's new location. 

One specific advantage of an indexed file over a relative 
file is that an indexed file allows you to search for records 
using several different key fields, while only the cell number can 
be used with relative files. Even with a single key, indexed 
files offer keys consisting of any ASCII characters, in contrast 
to just a cell number for relative files. 

There is, of course, more space overhead required in the file 
for the index structures. In addition, more execution time is 
required to insert new records, because the index structures must 
be updated as well. We are keeping things rather simple in the 
discussion here. For additional information, see the 
RMS-11 User's Guide. 



411 



FILE I/O 



Record Formats 

RMS supports three record formats; fixed-length record>s, 
variable-length records, and variable-length records with fixed 
control. Fixed-length records and variable-length records are the 
same as fixed-length records and nonsequenced variable-length 
records respectively, under FCS. They are both supported under 
all three file organizations. 

Variable-length records with fixed-control (VFC) contain a 
fixed-length portion, for control, followed by a variable-length 
portion. The fixed control portion may be up to 255(10) bytes 
long. A sequenced variable-length record under FCS is the same as 
a VFC record with a 2-byte (one word) fixed control portion. 

An example of the use of VFC records is a bank account file, 
where some accounts have both savings and checking, and others 
have just one or the other. The fixed control portion could 
contain the account number plus an indication of the kinds of 
accounts contained in it. The variable portion contains the 
account information for those accounts. The length of this 
portion varies, depending on how many accounts the person has. 
VFC records are supported under sequential and relative file 
organizations only. 



Record Access Modes 

RMS supports three record access modes: sequential access, 
random access, and access by Record File Address (RFA) . 
Sequential access and random access are similar to the FCS access 
modes, except that they are applied differently for indexed files. 

For sequential access on an indexed file, the "next" record 
is the record with the next highest key value using the specified 
key, not the next record added to the file. For random access, a 
key value for a certain key is specified, and that record is 
located and accessed. To access a record-by-record file address, 
save pointers to the record (called its record file address or 
RFA) from one access, then use the pointers to subsequently access 
the record again. 

Table 9-5 describes the various access modes supported for 
each file organization and how they work. For additional 
information, see the RMS-11 User's Guide. 



412 



FILE I/O 



Table 9-5 File Organization, Record Formats, and Access 



Record 
Fo rmats 
Supported 



Sequential 
Files 

Fixed 

Variable 

VFC 



Relative 
Files 

Fixed 
Va r i able 
VFC 



Indexed 
Files 

Fixed 
Variable 



Access Modes 
Supported 



Sequential 
RFA 



Sequential 

Random 

RFA 



Sequential 

Random 

RFA 



Sequential 

Access 

Techniques 



Writes and 
reads subse- 
quent records 



Writes to 
subsequent 
eel 1 s 

Reads from sub- 
sequent cells, 
skipping empty 
ones 



Accesses cells 
in ascending 
order accord- 
ing to user 
specified key 



Random 
Access 
Techniques 



Not allowed 



User specifies 
cell number of 
record to be 
accessed 



User specifies 
key and key 
value to be 
used in 
accessing 
records 



Record File 

Address 

Techniques 



Task can 
store RFA of 
a record for 
later return 



Same as sequen- 
tial files 



Same as 

sequential 

files 
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File Sharing Features 

RMS offers more sophisticated file-sharing options than FCS. 

Sequential files can be shared for read access only. Relative and 

indexed files can be shared for read and write access. When 

opening a relative or indexed file, a task indicates one of the 
following options. 

• No other accessor can change data in the file while it has 
access ("shared" read, exclusive "write"). 

• Other accessors can change data, but subsets of the file 
are protected at a time, while in use. 

Relative and indexed files are divided into units called 
buckets (of user specified size, each 1 to 32(10) blocks long) . 
In fact, all actual I/O tranfers are performed on full buckets 
only. In implementing protection of subsets of the file at a 
time, protection is on a bucket-by-bucket basis (bucket-locking). 

A bucket is locked from the time any task with write access 
accesses a record in a bucket, until that task begins operations 
on another bucket, or closes the file. This means that records 
within a given bucket can't be accessed by other tasks while 
another task with write access is using the bucket. But other 
tasks may access other buckets in the file during that time. 
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Summary 

An a Program. 

Table 9-.* rnm 
Characteristics Kcs C ° m ^^n of FCS and RMS 

Supportinq 
utilities 



Supporting 
lang uages 



Ease of 
fi le design 

Ease of 
Programming 



Standard rcv 
utilities * 

MACRO-l 1 



tolell™ 5 Uti ^ties 
etc ' Convert , 



~'7f BASIC-Ii 
Relatively simple 



FORTRAN IV, i V _ Prn ,, *»ACR -1 1 

~ 7 ?, BASIC-U S ' FORTRAN IV-PLUS 

-77, BASlC-PLfjqlo 
COBOL fLUb-2 



Type of data 
access supported 



y eveI languages 



derate in MACRo-n 

Virtual block i/ 

Sequential record 
access 

Random access bv 

-Length records 



Access by record 
Position pointers 

acce e s d s f o r r 

Bis of record 



Relatively complex 

£«.V< «"'"■«"' 

Relatively diff irnl . 
m MACRo-n CUlt 

Virtual block 1/0 

Sequential record 
access 

Random access by 

"^number in a 
relative fii e 

Random access bv 
ke y field within 
reco ^, i n an 

indexed fii e 

Access by record 
fl *e address 

a S cce1 s f n r ? m Previ °us 
ccess of record 
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Table 9-6 Comparison of FCS and RMS (Cont) 
Characteristics FCS RMS 



Overhead in file Minimal 
needed to support 
record structure 



Execution time 
overhead to 
support record 
access 



Shared access 
coord inat ion 



Low 



System protection on 
a per-file basis or 
on an all blocks 
accessed basis 



Minimal for se- 
quential files 

Moderate for 
relative files 

High for indexed 
files 

Low for sequential 
and relative files 

Moderate to high 
for indexed files, 

depending on file 
and program design, 
and file growth 

System protection 
on per-file or 
per-bucket basis 
within a file 



Now do the tests/ exerc ises for this module in the 
Tests/Exercises book. They are all written problems. Check your 
answers against the provided solutions in the Tests/ Exercises 
book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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FILE CONTROL SERVICES 



INTRODUCTION 

The File Control Services (FCS) subsystem provides the means 
through which most tasks perform file I/O. You make calls 
directly to the FCS routines. 

This module introduces you to the structure of FCS, the 
services it offers, and the ways in which you can use those 
services. 



OBJECTIVES 

1. To choose file characteristics for a specific application, 
then create a file with those characteristics 

2. To write tasks which read or write data using record I/O 
or block I/O (MACRO only) 

3. To identify and implement methods of optimizing file I/O. 



RESOURCE 

• IAS/RSX-11 I/O OPERATIONS MANUAL , Chapters 1, 2, and 3 
(Additional reading - Chapters 4 and 6) 
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REVIEW OF FILE I/O 

Use the following basic steps to perform file I/O. 

1. Open the file. 

• Ask ACP to connect LUN to file. 

• Specify access rights desired (RWED) . 

• Specify type of access. 

- Block I/O or record I/O 

For record I/O only 

Random or sequential access 
Move or locate mode 

• If new file, specify file characteristics. 

Record type 
Record attributes 

File initial size and extend size 

2. perform the actual I/O operations. 

3. Close the file. 

• Perform any needed clean-up work. 
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INTRODUCTORY EXAMPLE 

We begin our discussion of FCS with an example. The purpose 
is to give you a feeling for how to perform the basic steps of 
file I/O. After that, we will examine the data structures 
involved, and the specific steps for setting them up and using 
them to perform file I/O. 

Example 10-1 creates a file with variable-length records 
using sequential access. The records are input from TI : and then 
placed in the file. The following notes are keyed to the example. 

Q The interface with FCS is through system macros. 

Q FCSERR is an error message macro supplied with this 
course. Its source and documentation concerning its use 
are in Appendix A. It is used here to avoid having to 
worry about the details of the code. 

Q The FSRSZ$ macro reserves space in the user task for a 
general FCS data area which is called the file storage 
region (FSR). This macro must be issued in every program 
that uses FCS. 

O A file descriptor block (FDB) contains data structures for 
a file opened by FCS. A separate FDB is required for each 
file which is open at the same time. The FDB and its 
related data structures can be filled in at assembly time 
or at run time. in this example, they are set up mostly 
at assembly time, which is more run time efficient. 

Open the new file VARI.ASC. Notice that the run-time 
macro references the label of the FDB. This is necessary 
in the case of multiple FDBs , for multiple files opened by 
a single program. 

O Get input record from TI : . 

Q Write (PUT$) the record to the file. For variable-length 
records, specify the record length in bytes. 

Q Branch on any FCS error . 
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Get next record. On a ~Z, close the file and exit. 

On the Dump - A file dump is included for each example in 
this module which creates a new file. The dumps were 
created using the DMP utility, and are in octal byte 
format. Because this file has variable-length records, 
the first word in each record is a byte count for the 
record. See the section on FCS File Organizations in the 
File I/O module for additional information on the dump. 
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i 



•[ 



3 
4 
5 
6 
7 
8 
9 
10 
11 

13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
"24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
"36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
L48 



♦TITLE CRESEQ 
♦ I DENT /Ol/ 
* ENABL LC 



5 Enable lower case 



? File CRESEQ ♦ MAC 



y CRESEQ creates a file U ARI*ASC of variable- length 

y records using sequential access* It reads records from 

9 Tllr and places them in the file* A "'Z terminates 

i input and closes the file* 

9 

i Assemble and task-build instructions* 

9 

9 MACRO/LIST LB I C 1 1 1 UPROGMACS/LIBRARY r dev I Cuf d3- 

9 ->CRESEQ 

9 LINK/MAP CRESEQ , LB J 1 1 y 1 3PR0GSUBS/LIBRARY 

9 

♦MCALL EXST$CyGiaW*CyQIOW*yDIR* y System macros 

♦ MCALL FSRSZ*fFDBBF*»FDAT*A»FDRC$A»FDOP$A ? System 

* MCALL NMBLK*yOPEN$Wy PUT* y CLOSE* 5 FCS macros 

♦MCALL DIRERRy I0ERR * FCSERR J Supplied macros 



9 Define 
FDB ♦ 



SRSZ* 1 
file descriptor 



FDBDF* 
FDAT*A 



block 
R.VAR*FD*CR 



9 1 file for 
for VARI.ASC 



record I/O 



FDRC*A 9 BUFF 



fname: 
buff: 

IOSTi 



FH0P*A 

NMBLK* 

♦ BLKB 

♦ BLKW 

♦ EVEN 

♦ ENABL 



ly 9 FNAME 

VARIyASC 
80* 

2 

LSB 



A 1 1 o c a t e the F D B 

Variable length records? 
Listing - implied 
<CR> 9 <LF> 

Sequential access and 
record I/O by 
default.* BUFF is 
user record buffer 

Use LUN ly file spec 
at FNAME 

■VARI.ASC 

User Record Buffer 

I/O status block 



file for 
0PEN*W 



write 9 call ERR1 

#FDB 9 9 9 9 9 »ERR1 



Enable 
block 
if open 



local symbol 
f ai Is 



i Open 

start: 

9 Get record from terminal* put to file* 
10$: QI0W*C I0*RVBy5»lyyI0STyy<BUFFy80*> 

BCS ERR2D y Branch on directive 

5 error 

TSTB I0ST ? Check for I/O error 

BLT ERR2I y Branch on I/O error 



Example 10-1 Creating a File in MACRO-11 (Sheet 1 of 2) 
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of 49 

© 51 
©52 

53 



54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 



EXIT* 



MOV 
PUT* 
BCS 
BR 

CLOSE* 
EXST*C 



I0ST+2yRl 
#FDBy yRl 
ERR3 
10* 



y Number of bytes input 
? Put record to file 
f Branch on FCS error 
9 Get next record 



r Error code ~ 
r message and e 
ERR1J FCSERR 
ERR2D ♦ BIRERR 
ERR2.T * CMPB 
BEQ 



#FBByERR4 ? Close file 

EX*SUC i Exit with success 

9 status 
file if necessary y display error 



Close 
xit 

#FDB 9 <ERR0R OPENING 
^DIRECTIVE ERROR ON 
#IE.E0F»I0ST 
EXIT 



ERR3J 
ERR4 ♦ 



I0ERR 

CLOSE* 
FCSERR 
FCSERR 
♦ END 



FILE> 
RE Alib- 
is it "Z? 

If eaualy close file 
9 and exit 
#I0STy<ERR0R ON READ> i Display error 

9 message and exit 
♦FDByERR4 y Close file 

#FDB 9 <ERR0R UR I TING REC0RD> 
#FDB y <ERR0R CLOSING FILE> 
START 



Run Session J 

>RUN CRESEQ 
1111 

333 

JAZZ Jazz JAZZ Jazz 

Have you ever seen the sun? 

66 66 66 66 

~Z 



Dump of DBi:C305y301. - 3VARI»ASC527 - File ID 34772y6y0 

Virtual block Oy 000001 ~ Size 512* bytes 

O00000 004 000 061 061 061 061 010 000 062 062 062 062 062 040 062 062 

000020 003 000 063 063 063 000 023 000 112 101 132 132 040 112 141 172 

000040 172 040 112 101 132 132 040 112 141 172 172 000 033 000 110 141 

000060 166 145 040 171 157 165 040 145 166 145 162 040 163 145 145 156 

000100 040 164 150 145 040 163 165 156 077 000 013 000 066 066 040 066 

.000120 066 040 066 066 040 066 066 000 000 000 000 000 000 000 000 000 

Example 10-1 Creating a File in MACRO-11 (Sheet 2 of 2) 
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$$FSR1 
(BLOCK 
BUFFER 
POOL) 



$$FSR2 < 



BLOCK BUFFER 



BLOCK BUFFER 




BLOCK BUFFER 



IMPURE DATA 



Figure 10-1 The File Storage Region 
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USING FCS 

In this course, we cover many of the options supported by 
FCS. However, we cannot cover all of the options in detail. 
Therefore, it is very important that you read the reading 
references mentioned in the IAS/RSX-11 I/O Operations Reference 
Manual for further information. This is especially important if 
you are going to use an option which is not discussed in detail in 
this course. For a general discussion of FCS and its use, read 
Chapter 1 of that manual. 



Preparing to Open a File 

The File Storage Region (FSR) — The FSR is an area allocated 
in your task as working storage for FCS operations. The FSR 
consists of two program sections which are always contiguous to 
each other. Figure 10-1 shows the layout of the FSR. The program 
sections and their purposes are as follows. 

$$FSR1 — contains space for block buffers and the block 
buffer headers for record I/O operations. You determine the 
size of this area at assembly time with the FSRSZ$ macro. 
Block buffers and headers are allocated from this area when a 
file is opened for record I/O operations. Enough space must 
be allocated for the greatest need of your task at any one 
time . 

$$FSR2 — contains impure data which is used and maintained by 
FCS when performing both record I/O and block I/O operations. 
The area is set aside at assembly time. Portions of it are 
initialized at task-build time; other portions are maintained 
by FCS at run time. 

The data flow during record I/O operations for locate mode 
and move mode is shown in Figure 10-2. Note that blocks of data 
are transferred directly between the device and the FSR block 
buffer. In locate mode, you usually access the data directly in 
the FSR block buffer. In move mode, an additional transfer is 
made of the specified record between the FSR block buffer and a 
user specified buffer. 

The data flow during block I/O operations is different, as 
show in Figure 10-3. Blocks of data are transferred directly 
between the device and a user specified buffer. No FSR block 
buffer is needed. 
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MOVE MODE 



TASK 

(IN MEMORY) 




DISK 




MOVE 
BLOCK 

(IF NECESSARY) 



ABC • • • | 




MOVE 
RECORD 
















ABC • • • 













USER RECORD 
BUFFER 



FSR BLOCK 
BUFFER 




TK-7729 



ure 10-2 Move Mode Versus Locate Mode for Record I/O 
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TASK 

(IN MEMORY) 




TK-8636 



Figure 10-3 Block I/O Operations 



Initialization of the FSR 

Use the FSRSZ$ macro to establish the size of the FSR at 
assembly time. This macro must be used in any program using FCS, 
whether for block I/O or record I/O. The format of the FSRSZ$ 
macro is as follows. 

FSRSZ$ f buf s ,buf si ze ,psect 

fbufs - for block I/O only, specify 

- for record I/O or record and block I/O, maximum 
number of buffers needed for record I/O 

bufsize - total space needed for block buffers (in bytes) . 
Defaults to fbuf*512(10) 

psect - return Psect if other than default. 
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Ex am pi e s : 
FSRSZ$ 

Using FCS for block I/O only. Allocate FSR space for impure 
data only ($$FSR2) . 

FRSRSZ$ 2 

Using FCS, allocate FSR space for impure data ($$FSR2) , and 
for record I/O block buffers ($$FSR1) . Total allocation for 
block buffers in $$FSR1 is two headers plus 2*512(10) 
1024(10) bytes. 

FSRSZ$ 3,2048 

Using FCS, allocate FSR space for impure data ($$FSR2) , and 
for record I/O block- buffers ($$FSR1) . Total allocation for 
block buffers is three headers plus 2048(10) bytes. For 
example, two are 512(10) bytes long and the third is 1024(10) 
bytes long. 

The buffer size usually corresponds to a disk block (512(10)) 
for disks, or the buffer width for terminals. If all record I/O 
operations use single buffering with the default buffer size of 1 
disk block (512(10)) , then fbufs should be the maximum number of 
files open at the same time for record I/O. Bufsize can be 
defaulted to that number, times 512(10). 

If double buffering is used for some record I/O operations, 
or larger block buffers are desired (to reduce the number of I/O 
transfers) , specify values for fbufs and/or bufsize. This allows 
for your maximum need for files open at the same time for record 
I/O. 

See section 2.6.1 on FSRSZ$ in the IAS/RSX-11 Operations 
Reference Manual for a discussion on how to calculate bufsize. 
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The File Descriptor Block (FDB) 

Functions of the FDB - The FDB contains information used by FCS in 
opening and processing a file. One FDB is required for each file 
that is open at the same time by your program. An FDB may be 
reused once the file associated with it is closed. The FDB is 
used by: 

• The task, to pass information to FCS 

• FCS, to return information to the task 

• FCS, for internal bookkeeping for the file. 

You must allocate space for each FDB and initialize specific 
portions, before opening a file. You may use either assembly-time 
or run-time macro calls. Figure 10-4 shows an FDB and its 
different parts. 



FILE DESCRIPTOR BLOCK 



FILE ATTRIBUTE 
SECTION 



RECORD OR BLOCK 
ACCESS SECTION 



FILE OPEN SECTION 



BLOCK BUFFER 
SECTION 



FILE NAME 
BLOCK SECTION 



RECORD TYPE AND SIZE 
FILE TYPE AND SIZE 



BUFFER DESCRIPTORS AND 
POINTERS - ACCESS MODE 



ASSOCIATED LUN 



MULTI-BUFFERING DESCRIPTOR 
BUFFER SIZE 



FILE SPECIFICATION 
FILE ID 



FDAT$A 



FDRC$A AND 

FOR BLOCK FDBK$A 



FDOP$A 



FDBF$A 

POINTERS IN FDOP$A 
(BUILT AT OPEN FROM 
DSPT OR NAME BLOCK 
PLUS INFO. FROM FILE) 



Figure 10-4 The File Descriptor Block 
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Allocating Space for FDBs - Use the FDBDF$ macro to allocate space 
for one FDB . The format of the call is: 

label : FDB DF $ 
FDB IN: FDB DF $ 



The label is used later to refer to a specific FDB. 

Initializing an FDB - You can initialize an FDB either at assembly 
time or at run time. Whenever possible, use the assembly-time 
macros because they do not need to be executed at run-time. 
Therefore, your task will be more run-time efficient. With the 
assembly-time macros, use parameters which are valid source 
arguments for .WORD or .BYTE assembler directives. Many values 
have symbolic equivalents which can be used instead of the actual 
numeric values. 

With the run-time macros, use parameters which are valid 
source arguments for MOV or MOVB instructions. This is similar to 
the convention for the $ form versus the $S form of the executive 
directives. At assembly time, use FCS macros which end with $A; 
at run time, use FCS macros which end with $R. The assembly-time 
macros must immediately follow the FDBDF$ macro which reserves 
space for the FDB. The run-time macros have an additional initial 
argument to specify which FDB they refer to. 

Run-time initialization macros override any previous FDB 
settings. in addition, you can also override the settings in the 
file open operation or in an I/O operation. 

As an aid in referencing a given FDB at run time, all FCS 

run-time initialization and fi le- processing macros return the FDB 

address in R0. If no FDB pointer is specified in subsequent FCS 

macro calls, it defaults to R0. The other registers are saved and 
restored by all FCS run-time macros. 

For additional information on the use of parameters in the 

different forms of the FCS macro calls, see section 2.2.1 on 

Assembly-Time FDB Initialization Macros, and section 2.2.2.1 on 

Run-Time FDB Macro-Call Exceptions in the IAS/RSX-11 I/O 
Operations Reference Manual . 

The following sections describe how to use the different FCS 
FDB initialization macros to initialize an FDB. 
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Specifying New File Characteristics 

Use either the FDAT$A macro, at assembly time, or the FDAT$R 
macro, at run time, to specify new file characteristics. These 
macros are only required where you create a new file. FCS uses 
the established characteristics for existing files. The format of 
the FDAT$A macro is: 

FDAT$A rtyp,ratt,rsiz,cntg ,aloc 

rtyp - record type 

R.FIX = fixed length 
R.VAR = variable length 
R.SEQ = sequenced 

ratt - record attributes 

carriage control 

FD.FTN = FORTRAN type 
FD.CR = list type 

default = no implied carriage control 

spanning of blocks 

FD.BLK = spanning blocks not allowed 
default = spanning blocks is allowed 

rsiz - record size 

cntg - initial number of blocks for file 
aloe - extend size for file. 
Examples : 

1. FDAT$A R.VAR 

File will have variable-length records. Defaults: no 
implied carriage control, may span block boundaries, 
initial size of zero blocks, default extend size, on 
disk, generally five blocks. 

2. FDAT$A R.FIX, FD.CR, 64. 

File will have fixed-length records, list carriage 
control, and 64(10) byte records. Defaults: records may 
span block boundaries, initial size of zero blocks 
default extend size. 
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3. FDAT$A R. FIX, RD. FTNi FD.BLK,100. ,-15 . 

File to have fixed-length records, FORTRAN type carriage 
control; records may not span block boundaries; 100(10) 
byte records, initial file size of 15(10) blocks, not 
necessarily contiguous. Default: default extend size. 

4. FDAT$R #FBD1,#R.FIX,#FD.FTN! FD.BLK,#100. ,#15. 

The same as the previous example, but using the run-time 
form. 

Note the difference in the format of the parameters in the $A 
(for assembly-time) and the $R (for run-time) forms. For the $A 
form, the parameters are symbolic or numeric values, all valid 
source arguments for .WORD or .BYTE assembler directives. For the 
$R form, on the other hand, the parameters are all valid source 
arguments for MOV or MOVB instructions. 

If records are allowed to span block boundaries, then a 
record at the end of a block, which doesn't fit completely within 
the block, is continued in the next block. If records are not 
allowed to span block boundaries, a record which doesn't fit 
completely is started at the beginning of the next block. The 
space remaining in the current block is unused. This technique 
uses more file space, but permits quicker I/O operations in locate 
mode . 

Specify one of three possible types of carriage control in 
the ratt parameter. FD.FTN indicates that the first data byte of 
each record contains a FORTRAN carriage-control character (e.g., 
space for single space, for double space) . FD.CR indicates that 
when the record is written to a line printer or a terminal, each 
record is to be preceded by an <LF> character and followed by a 
<CR> character. This causes single spacing between records in the 
printout. if you specify neither FD.FTN nor FD.CR, no carriage 
control is implied. Any carriage control characters must be 
imbedded in the data. List ( . LST) files are set up with no 
implied carriage control. 

See section 2.2.1.2 on FDAT$A in the IAS/RSX-11 I/O 
Operations Reference Manual for additional information on the 
FDAT$A parameters. 
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Selecting Data Access Methods 

First decide whether to use block I/O or record I/O. 
Normally use block I/O for files with no record structure, and 
record I/O for record structured files. However, block I/O is 
faster than record I/O, because no blocking or deblocking of 
records is required, and transfers are made directly between the 
device and the user buffer. Therefore, if your operation does not 
require accessing individual records within the file, e.g., a file 
copy operation, use block I/O because it is more efficient. 

After you select block I/O or record I/O, there are some 
other considerations. For block I/O, no FSR block buffer is 
needed. Instead, you must specify a user buffer. Block I/O is 
asynchronous; set up an event flag or an AST for synchronization. 
Also, you must use the additional FDBK$A or FDBK$R macro to 
specify the user buffer and the synchronization techniques. 

For record I/O, choose either sequential access or random 
access mode. Sequential access can be performed on files with 

either var iable- leng th records or fixed-length records. 

Successive PUT$ or GET$ operations in sequential access mode 

access successive records in the file. This is useful if you need 

to process all records in the file in order. It is required if 
the file has variable-length records. 

Random access can be performed only in files with 
fixed-length records. With random access, your program can access 
records randomly by specifying a record number in each PUT$ or 
GET$ call. Random access is desirable if you want to access 
records in an order which is different from their order in the 
file. 

With sequential access, you can use FCS routine to save 
pointers to an accessed record, and later return to that record. 
This offers you a limited ability to access records in a random 
order, or at least an ability to back up to a certain point in the 
file and continue from there. The actual subroutines are 
discussed later in this module under Performing I/O. 

For record I/O, an FSR block buffer is used for the actual 
I/O transfers. Blocking and deblocking of records is done 
transparently for you by FCS. When FCS blocks a record on output, 
it places it into one or more virtual blocks as needed. When FCS 
deblocks a record on input, it takes one or more virtual blocks 
and constructs a logical record. Because GET$/PUT$ operations, 
used for record I/O, process records which are contained in 
virtual blocks, not all I/O operations cause an actual I/O 
transfer. Generally, an I/O transfer is needed only when the end 
of a block is reached. 
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You may choose either move mode or locate mode. Figure 10-2 
compares the two. In move mode, you always access records in a 
user specified buffer, sometimes called a user record buffer. 
Move mode is simple to program, but every PUT$ or GET$ operation 
requires an extra transfer of the record between the user record 
buffer and the FSR block buffer. A user record buffer is 
required. 

In locate mode, as long as complete records are located 
totally within an FSR block buffer, you access the record directly 
in the FSR block buffer. FCS returns information in the FDB about 
the location and the size of the record. If records are allowed 
to span block boundaries and the last record in a block does span 
the block boundary, then the full record cannot be accessed until 
the next virtual block is read (in the case of a GET$ operation) , 
or until the current virtual block is written (in the case of a 
PUT$ operation). In that special case, the record is accessed in 
a user specified buffer. Therefore, a user record buffer is 
required in locate mode only if one or more records actually span 
block boundaries. Table 10-1 summarizes the situations when a 
user record buffer is needed. 

Record I/O operations are synchronous. All synchronization 
is handled for you by FCS. Control is returned to your program 
only after the requested PUT$ or GET$ operation is completed. 



Table 10-1 When the User Record Buffer Is Needed 



Mode I/O Operation 

Move GET$ 

Locate GET$ 



If Records 
Span Block 
Boundar ies 

Needed 

Needed 

Needed 

Needed 



If Records 
Do Not Span 
Block Boundaries 

Needed 
Needed 
Not needed 
Not needed 
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Specifying Data Access Methods 

Use the FDRC$A or the FDRC$R macro to specify data access 
methods . 

FDRC$A race ,urba ,urbs 

race - type of access 

methods 

FD.RWM = block mode 

FD.RAN = record mode, random I/O 

default = record mode, sequential I/O 

file truncation 

FD. INS = PUT$ in middle of file does not truncate 
file 

default = does truncate file 

move or locate 

FD.PLC = locate mode 
default = move mode 

urba - user record buffer address (Table 10-1) 

urbs - user record buffer size (in bytes) . 

Examples : 

1. FDRC$A , BUFF, 80. 

Defaults to record I/O, sequential access in move mode. 
User record buffer at BUFF, 80. bytes long. 

2. FDRC$A FD.RWM 

Block I/O. buffer is specified in FDBK$A macro or in 
open, READ$, or WRITE$ macros. 

3. FDRC$R #FDB4,#FD. RAN! FD. PLC ,#BUFF,#100. 

Record I/O, random access in locate mode. User record 
buffer at BUFF, 100. bytes long. This is a run-time 
macro which initializes the FDB at FDB4. 
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If FD. INS is not specified, a PUT$ in the middle of the file 
places the logical end-of-file right after that record, which 
truncates the file. If FD. INS is specified, a PUT$ in the middle 
of the file does not change the logical end-of-file. See section 
2.2.1.3 on FDRC$A in the IAS/RSX-11 I/O Operations Manual for 
additional information. 



Additional Initialization of the FDB for Record I/O 

Normally, no further initialization is needed for record I/O. 
However, if you wish to override one or more of the defaults, use 
the FDBF$A or the FDBF$R macro. The defaults are included in the 
list of parameters below. The format of the FDBF$A call is: 

FDBF$A ef n ,ovbs ,mbc t ,mbfg 

efn - event flag used internally for synchronization 
(default is 32(10)) 

ovbs - override FSR block buffer size (in bytes) (default 
is standard block size for device) 

mbct - multiple buffer count (default generally 1, or 
single buffering) 

mbfg - multiple buffering type (only for multiple buffering) 

FD. RAH = read ahead operations 

FD.WRB = write behind operations 

(default - FD. RAH if file opened for read only, 

FD.WRB if file opened for a write operation) 

Examples : 

1. FDB F$A ,,2 

Use double buffering. Defaults: event flag 32(10) , FSR 
block buffer size standard for device (e.g., 512(10) 
bytes for disk) . Multiple buffering type - read ahead if 
file is opened for read only, write behind if it is 
opened for a write operation. 

2. FDBF$A 12. ,2048. 

Use event flag 12(10) and an FSR block buffer size of 
2048(10) bytes. This is the standard size for ANSI 
magtape. It can also be used for disks to cut down on 
the number of I/O transfers. Default: single buffering. 



438 



FILE CONTROL SERVICES 



In the second example, you must reserve enough space in the 
FSR using the FSRZ$ macro. See section 2.2.1.6 on FDBF$A in the 
IAS/RSX-11 I/O Operations Reference Manual for further informa- 
tion . 



Additional Initialization for Block I/O 

For block I/O, you only specify the access method in the 
FDRC$A or FDRC$R macro. You must use the FDB K $ A or FDBK$R macro 
to set up the user buffer and your synchronization methods. The 
format of the FDBK$A macro is as follows. 

FDBK$A bkda ,bkds ,bkvb ,bkef ,bkst ,bkdn 

bkda - user buffer address 

bkds - user buffer size (in bytes) 

bkvb - address of two-word virtual block number 

bkef - event flag for synchronization (default = 
32 (10) ) 

bkst - I/O status block address (must be specified 

for FCS to return I/O status) 

bkdn - AST service routine address 

NOTE 

Bkvb must be specified after the file is 
opened using the $R form, or in a READ$ or 
WRITE$ call. 

Example: 

FDBK$A MYBUF,1024. , ,20. , IOST 

User buffer at MYBUF, size is 1024(10) bytes. Use event flag 
20(10), the I/O status block is at IOST. No AST routine. 

Bkvb is the address of a two-word data block containing the 
first virtual block number for a block I/O operation. This data 
block is copied into the FDB and then used to locate the starting 
block for the I/O operation. 
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However, the virtual block number in the FDB is always 
initialized to '1' when a file is opened. Therefore, this 
parameter must be specified after the file is opened if you wish 
to start I/O operations with a block other than virtual block 1. 
Do this using either a FDBK$R, a READ$ , or a WRITE$ call. 

The parameter should be left null if you use the $A form. It 
is present in the $A form only for compatibility with the $R form. 

Bkst is the address of an I/O status block. Unlike record 
I/O, where FCS sets up its own internal I/O status block, block 
I/O requires that you specify an IOSB in order to get I/O status 
reports. FCS issues QIOs for you. With record I/O, FCS reports 
both directive errors and I/O errors automatically. With block 
I/O, I/O errors are reported only if you specify an IOSB address 
in a FDRK$A or FDBK$R call. 



Initializing the File-Open Section of the FDB 

You must also initialize the file-open section of the FDB 
before opening a file. It contains information about the file to 
be opened. You must set up data structures so that FCS can build 
a file specification for the file. In addition, you must specify 
the LUN to be assigned to the file and the kind of access rights 
you need (read, write, extend or delete) . You can do all of this 
with an assembly or run-time macro, or in the actual open macro 
call. 

Setting Up the File Specification in the FDB — At run time, FCS 
constructs a standard file specification in the filename block in 
the FDB using the following, in order: 

1. The dataset descriptor 

2. The default filename block 

3. Other defaults of the task or system 

FCS first uses any information which is set up in the dataset 
descriptor. Any non-null data is translated from ASCII to 
Radix-50 format, and stored in the appropriate offsets in the 
filename block. If any pieces of the file specification are not 
specified in the dataset descriptor, FCS next checks the default 
filename block for any of the missing pieces. Any missing pieces 
which are found there are filled in next. 
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If the device or the UFD is still not filled in, normal 
system defaults are used. The device defaults to the current LUN 
assignment of the LUN to be used to access the file. The UFD 
defaults to the default UIC of the task, which is typically the 
default UIC of the user who runs the task. If the file name or 
the file type are still not filled in, a file open failure occurs. 

If only a dataset descriptor or a default filename block is 
specified, and not both, the missing structure is skipped. 
Typically, the dataset descriptor is used for building file 
specifications at run time. Several routines (get command line 
(GCML) , command string interpreter (CSI), etc.) are available for 
prompting for input, getting a command line, and then filling in a 
dataset descriptor. Typically, the default filename block is used 
to default any fields not specified in the dataset descriptor, or 
to completely set up a file specification at assembly time. 
However, one or both structures may be set up at assembly time, if 
desired. 

If you want to have FCS perform I/O to a terminal, just build 
a file spec with the device TTnn : or TI:. If the specified 
device is a terminal, FCS just issues QIOs to the terminal. The 
advantage of this technique over issuing QIOs yourself is that the 
same I/O routines work correctly with file-oriented devices and 
terminals. You do not have to rewrite the I/O code to change 
between device types. The system utility PIP uses FCS calls for 
all of its I/O operations. 



Setting Up the Dataset Descriptor 

The dataset descriptor is a six-word data area in your 

program containing the sizes and the addresses of the ASCII data 

strings that together make up a file specification. The format of 
the data area and the ASCII strings is: 

label: .WORD ldev,adrdev 
.WORD lufd,adrufd 
.WORD lnam,adrnam 



adrdev: .ASCII /dev/ 

ldev =. -adrdev 

adrufd: .ASCII /ufd/ 

lufd =. -adrufd 

adrnam .ASCII /full name/ 

lnam =. -adrnam 
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Example for file DB 1 : [202,1] SAMPLE . MAC : 



DSPT: 


.WORD LDEV, DEV 




.WORD LUFD, UFD 




.WORD LNAM, NAM 


DEV: 


.ASCII /DB1 :/ 


LDEV 


=.-DEV 


UFD 


.ASCII /[202,1]/ 


LUFD 


=.-UFD 


NAM: 


. ASCI I/SAMPLE . MAC/ 


LNAM 


= . -LNAM 



This example sets up the dataset descriptor and all of its 
file specification pieces at assembly time. This can also be done 
at run time. As shown above, FCS builds the file spec 
DB1 : [202 , 1] SAMPLE. MAC . If no default filename block is specified, 
the version number takes the normal system default, the latest 
version for an existing file, and the latest version, plus one, 
for a new file. See section 2.4.1 on the Dataset Descriptor of 
the IAS/RSX-11 I/O Operations Reference Manual for additional 
information. 



Setting Up the Default Filename Block 

The default filename block is an area within your program 

containing the various elements of a file specification. Use the 

NMBLK$ macro call to both reserve space for this area, and to 

initialize it at assembly time. The format of the NMB LK $ call is: 

label: NMB LK $ fnam ,f typ,f ver ,dvnm ,uni t 

Example for file DB1 : SAMPLE. MAC : 

NMBLK$ SAMPLE, MAC, DB , 1 



Notice that you divide the file specification into pieces in 
the macro call. Also note that you cannot specify a UFD in the 
default filename block. ; It can be specified using a dataset 
descriptor. Otherwise, it is usually taken from the default UIC 
of the task. 

See section 2.4.2 (on Default Filename Block - NMB LK $ Macro 
Call) for additional information on the default filename block. 
It also explains how to manually define or override data in the 
default filename block. 
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Initializing the File-Open Section Prior to Opening the File 

Use the FDOP$A or the FDOP$R macro call. The format of the 
FDOP$A call is as follows. 

FDOP$A lun , dspt , df nb ,f acc ,actl 



lun 


- LUN for 


I/O requests 


dspt 


- pointer 


to dataset descriptor 


dfnb 


- pointer 


to default name block 


face 


- type of 


file access (Table 10-2) 


actl 


- access 


control 



The type of file access indicates the kind of activity that 
you will perform on the file. Table 10-2 lists these types. Note 
that you do not specify read, write, extend, or delete; but 
instead write, read, append, modify, or update. Each implies a 
request for a particular set of access rights. The meanings of 
the types are : 

write - Write (create) a new file. 

read - Read an existing file. 

append - Append (add) data to the end of an existing file. 

modify - Modify an existing file without changing its length. 

update - Update an existing file, extending its length if 
necessary. 

In all cases, the file can also be read. 
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The actl parameter is used to override the defaults for 
certain FDB control information, namely: 

• Initial magnetic tape position - default depends on file 
operation . 

• Locking of a disk file opened for write if it is not 
properly closed, e.g., if the task is aborted. Default is 
that the file is locked. 

• The number of retrieval pointers in pool for a disk file 
window. Default is volume default. 

• Enable or disable block locking. Default is disable block 
locking. 

See section 2.2.1.5 on FDOP$A in the IAS/RSX-11 I/O 
Operation Reference Manual for an explanation of the defaults, and 
the arguments to override them. This section also covers 
additional information on the FDOP$A and the FDOP$R macros. 

If desired, you can specify all of the FDOP$A or FDOP$R 
parameters, except actl, in the open macro call instead. The 
following examples show the use of the FDOP$A call, dataset 
descriptors, and default filename blocks. 
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Table 10-2 Types of Access 



FDOP$A 
face 
Class value 

Write FO.WRT 



Read FO.RD 
Append FO.APD 



Modify FO.MFY 



Suffix 
to Open 
Call 



R 
A 



M 



Update FO.UPD U 



New or 
Old File 

New 



Old 
Old 



Old 



Old 



Def aul t 
Location of 
Access Rights First I/O 



Requested 

Re ad 
Write 
Ex tend 

Read 

Read 
Wr i te 
Ex tend 



Re ad 
Wr i te 

Read 
Wr i te 
Extend 



Operation 
Beg inning 

Beg inning 

End (sequen- 
tial access) 
Beg inning 
(random 
access) 

Beg inning 
Beg inning 
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Ex am pi e s : 
1. 

FDOP$A I,, DFNB 



DFNB: NMB LK$ MYFILE, DAT, , DB , 



Use LUN 1, build the file spec in the FDB with the default 
filename block (since there is no dataset descriptor) . The 
file spec will be DB : MYF ILE. DAT. The UFD will be taken from 
the default UIC of the task; the version number takes the 
normal default. 

2. 

FDOP$A 2,DSPT 



DSPT: .WORD 0,0 

.WORD LUFD, ADRUFD 
.WORD LNAM, ADRNAM 

ADRUFD: .ASCII /[15,12]/ 

LUFD =. -ADRUFD 

ADRNAM: .ASCII /MYF ILE. FFF ; 3/ 

LNAM =. -ADRNAM 



Use LUN 2, build the file spec first with the dataset 
descriptor, then go to task and system defaults (since there 
is no default filename block) . The File spec will be 
[15, 12] MYF ILE. FFF; 3. The device will be defaulted to the 
current LUN assignment and to SY: if not currently assigned. 

3. 

FDOP$A 1, DSPT1,DFNB1,F0.WRT 



DFNB 1 : 
DSPT1: 



DEV: 

LDEV 

DNAM: 

LNAM 



NMB LK$ 
.WORD 
• WORD 
.WORD 
.ASCII 
=.-DEV 

.ASCII /MINE/ 
=.-NAM 



ANY , F I L 
LDEV, DEV 
0,0 

LNAM, NAM 
/DK2 :/ 
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Use LUN 1; open the file for write (create a new file) . 
Build the file spec first from the dataset descriptor, then 
fill in any missing information from the default filename 
block. The resulting file spec will be DK2 : MINE. FIL. The 
UFD and version number take normal system defaults. The 
filename is MINE because the dataset descriptor is used 
first. Since the name is then filled in, the default 
filename block is not checked for a name. 



Examples of Setting up an FDB 

The following examples show the complete process of setting 
up and initializing FDBs at assembly time before opening a file. 
Two examples are included for creating a new file, plus two for 
accessing an existing file. The line comments offer an 
explanation of the examples. 

Creating a New File: 



1. 



FSRSZ$ 



1 



1 file will be open for 
record I/O 



FDB 1 : 



FDBDF$ 
FDAT$A 



R. VAR, RD. CR 



Variable length records, 
"list" carriage control 
URB at BUFF, length 80. 
bytes. Defaults: sequential 
access, move mode 
Use LUN 2, file spec from 
Default Name Block 
File Spec VARIABLE. ASC 



FDRC$A 



,BUFF,80. 



FDOP$A 



2 



i t 



DFNB 



DFNB : 



NMB LK $ 



VARIABLE, ASC 
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2. 



FSRSZ$ 



FDB1 



DSPT 



NAM: 
LNAM 



F DB DF $ 

FDAT$A R.FIX,FD.FTN,80, 



FDRC$A RD. RAN, BUFF ,80 . 
FDOP$A 1,DSPT, ,FO.WRT 



.WORD 0,0 
.WORD 0,0 
.WORD LNAM, NAM 
.ASCII . /MINE.FIL;2/ 
= . -NAM 



Fixed length records, 

FORTRAN carriage control, 

80. byte records 

Random access, URB at BUFF, 

length is 80. bytes 

Use LUN 1, build file spec 

from dataset descriptor, 

open a new file for write 

Use default device 

Use default UFD 

Pointer to file spec 

File name 

Length of file name 



Accessing an Existing File 
1. 

FSRSZ$ 1 



FDB1 



FDBDF$ 

FDRC$A , URB, 25. 



FDOP$A 3 , , DFNB 



URB at URB, length = 25. 
bytes. Defaults: sequential 
access, move mode 
Use LUN 3, build file spec 
from Default Name Block 
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2. 



FSRSZ$ 



FDB1: 



FDBDF$ 
FDRC$A 
FDBK$A 



FD.RWM 
BUFF, 512. 



FDOP$A 2, , DFNB 



Only block I/O 



Block I/O, no URB needed 
For block I/O - sets up 
buffer at BUFF, length = 
512. bytes 

Use LUN 2, build file spec 
from Default Name Block 



LEARNING ACTIVITY 10-1 
The example below shows two FDBs . The second 
FDB is filled in to display a file at a 
terminal. Fill in the first FDB for a file 
YOURS. MAC, with variable length records which 
will be read and displayed. Use sequential 
access in locate mode. 



FSRSZ$ 



2 "Files" open for record I/O 



FDB I: 



To be filled in by the student 



FDBO: 



DSPTO 



DEV: 
LDEV 



FDBDF$ 

FDAT$A R. VAR, RD . CR 



FDRC$A , BUFF, 80 



FDOP$A 2, DSPTO 



.WORD 
.WORD 
.WORD 
.ASCII 
=. -DEV 



LDEV, DEV 
0,0 
0,0 
/TI:/ 



Variable length records, 
implied carriage return, 
line feed 

Sequential I/O, move mode, 
URB at BUFF, length = 80. 
bytes 

Use LUN 2, override LUN 
assignment. Build file spec 
using dataset descriptor 
pointers to ASCII data 



Device is TI: 
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Opening a File 

Whether or not you set the file access parameter with an 
FDOP$A or FDOP$R macro call, you can use the general OPEN$ macro 
call to open the file. If the access parameter is not already 
specified, specify it in the OPEN$ call. You can also use a 
number of other open macro calls, which have a single letter 
suffix to specify the file access. See Table 10-2 for the 
suffixes and their meanings. With file open macros, you can 
choose : 

• Whether shared access is allowed 

• Whether a file is permanent or temporary (deleted when 
closed ) 

• Which FCS object modules are used to open the file. 
The following list shows all of the possible open macros. 
OPEN$ f db ,facc,lun,dspt,dfnb,racc,urba,urbs,err 

General form 

File access specified in face or previously using 
FDOP$A or FDOP$R 

OPEN$x* fdb ,1 un ,dspt , race ,urba ,urbs , err 
Used for most applications 

Requests exclusive write access, shared read access 
OPNS$x fdb ,lun ,dspt , race ,urba ,urbs ,er r 

Allows shared access 
OPNT$D fdb ,1 un ,dspt , race ,urba ,urbs , err 

Opens temporary file, deletes when closed 
OFID$x fdb , 1 un , dspt, race, urba,urbs, err 

Opens file by file ID 
OFNB$x fdb ,1 un , dspt , race ,urba ,urbs , err 

Specifies file by file name block. 

* The "x" in the macro name represents one of the suffixes listed 
in Table 10-2. 
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Ex am pi e s : 

OPEN$ #FDB1, #FO.WRT, , , , , , , ERR1 

Open the file using the FDB at FDB1 for write access (create 
a new file). Call ERR1 on an error. All other information 
is already in the FDB. 

OPEN$W # F DB 1 , , , , , , ERR1 

The same as the last example, only using the other form of 
the call. 

OPNT$D #FDB3 r , , , , ,ERR2 

Open a new file as a temporary file using the FDB at FDB3. 
Call ERR2 on an error. 

OPNS$U R0 / #3 , , , , , ERR5 

Open the file for update using the FDB whose address is in 
R0. Allow shared access. Use LUN 3. Call ERR3 on an error. 

OPEN$ R0, #F0. UPD! FA.SHR,#3 , , , , , , ERR5 

The same as the last example, using the OPEN$ form of the 
call. 

OPEN$ 

Open the file using the FDB pointed to by R0. All 
information is already in the FDB. The user should check the 
carry flag for an error. 

There is no difference in functionality between the OPEN$ 
macro with the face argument filled in, and the OPEN$x, OPNS$x, or 
OPNT$D forms. Use the form which is most convenient. 

OFNB$x uses information already in the filename block of the 
FDB to open the file. When this occurs, FCS does not build a file 
spec prior to the open call. This is more efficient if the 
filename block is still intact, or has been restored after a 
previous open and close of the file. However, the OFNB$X call 
causes the Task Builder to include different object modules in 
your task, thus increasing your task's size. These will be 
additional modules unless OFNB$x is already used in your program. 
The same run-time savings can be achieved if you first fill in the 
filename block and then use an OPEN$, OPEN$x, or OPNS$x call, with 
no additional object modules added. 
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OPFNB$x is useful only in overlay situations, or when OFNB$X 
is already included. Note that the Get Command Line routine 
(GCML) uses OFNB$X. 

As shown in the last module, accessing a file-by-file 
specification involves a minimum of six disk reads (see Figure 
9-5). If you know the file ID of a file, opening the file-by-file 
ID reduces the number of file accesses to two. This is possible 
if you reopen a file for a second time or use other FCS routines 
to obtain the file ID. This is because the file ID allows direct 
access to the file header of the file. 

Any time the file ID field in the FDB is filled in, any open 
macro call automatically opens the file-by-file ID. The OFID$x 
call performs the same function, but like the OFNB$x call, it 
causes the Task Builder to include different object modules in 
your task, thus increasing its size. Therefore, fill in the file 
ID and use the regular open macros to open a file-by-file ID. 
Only use the OFID$x call in an overlay situation, or if OFID$x has 
already been included in your task. 
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ERROR CHECKING 

If an error condition is detected during any of the file 
processing operations, the FCS routines set the carry bit in the 
processor status word (PSW) , and return the error code and the 
type of error to FDB offset locations F. ERR and F.ERR+1. 

The run-time FDB initialization macros are an exception to 
this convention. They do not return any error indications because 
they involve only moves into FDB locations. The FCS 
file- processing routines issue appropriate QIOs for you. 

As with regular QIOs you issue yourself, directive errors or 
I/O errors can occur. For record I/O, FCS returns the error codes 
to the offset F. ERR of the FDB for you so that you don't have to 
check the I/O status block and the directive status word (DSW) 
directly yourself. The error codes are always returned as byte 
values. Since some of the error code values for directive and I/O 
errors overlap, another byte, offset location F.ERR+1 in the FDB, 
contains an indicator, whether the error was a directive or an I/O 
error. A value of '0* in F.ERR+1 indicates an I/O error, a 
negative value indicates a directive error. 

Therefore, to check for errors, check the carry bit on return 
from each file-processing FCS macro call. If there is an error, 
use a TSTB to check offset location F.ERR+1 to distinguish whether 
it is an I/O error or a directive error. Then, check and display 
the error code value. The following section of code shows a 
technique for doing this. 
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Example of Error Checking and Processing 

BUFF: . BLKB 80 ; Output buffer 

ARG: . BLKW 1 ; Argument block for $ EDMSG 

EDIR: .ASCIZ /FCS DIRECTIVE ERROR. ERROR CODE = %D./ 

EIO: .ASCIZ ?FCC I/O ERROR. ERROR CODE = %D.? 

. EVEN 



OPEN$W #FDB ; Open file 

BCS ERR1 ; Branch on FCS error 



;Error Processing 



ERR1: 


TSTB 


F.ERR+1(R0) ; 


Directive error or I/O 
error? 




BEQ 


10 \ 


) Branch on I/O error 




MOV 


#EDIR,R1 


• Addr of directive error text 
- f string for $EDMSG 




BR 


FINSET , 


} Branch to common code 


10: 


MOV 


#EI0,R1 , 


• Addr of I/O error text string 
; for $EDMSG signs 


FNSET: 


MOVB 


F . ERR (R0) , R0 


• Sign extend FCS error 




MOV 


R , ARG 


} code and place 




MOV 


#ARG,R2 


? in arg block 




MOV 


#BUFF,R0 


i Output buffer 




CALL 


$EDMSG 


; Edit error message 




QIOW$S 


#I0.WVB,#5, #1, , , , <#BUFF, Rl, #40> ; Display message 




BCS 


ERRQIO ; Branch on directive error 




EXIT$S 


; Ex i t 



ERRQIO: 

; Directive error code 



Using the READ$ and WRITE$ macros, directive errors are 
returned normally by FCS. Unlike record I/O, with block I/O FCS 
does not set up an internal IOSB for you. Therefore, you will not 
get I/O success or failure indications if you do not set up and 
specify an IOSB. 
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The error code is sign extended because $EDMSG works only on 
word values, not on byte values. The error codes and their 
meanings are listed in Appendix I of the IAS/RSX-11 I/O 
Operations Reference Manual . They are also in the RSX-11M Mini 
Reference . just the directive error codes are in Appendix B of 
the Executive Reference Manual , and just the I/O error codes are 
in Appendix B of the RSX-1 1M/M-PLUS I/O Driver's Reference Manual . 

You can also specify the address of your own error-handling 
routine, and specify it as the last macro call parameter. A JSR 
PC instruction to the specified user routine is generated. This 
takes the place of the BCS, and causes a call to the 
error-handling subroutine in the case of an FCS error. Note that 
it is a JSR PC which places the return address on the stack. You 
must clear off the stack for a nonfatal error if you do not use a 
return at the end of the error routine. 
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PERFORMING RECORD I/O 



Different Forms of PUT$ and GET$ 



The three different forms of the PUT$ and GET$ macros are: 
• GET$ and PUT$ 

Used for sequential access 

Can also be used for random access if either: 



Records are actually accessed in sequence 

Program manually changes record number field in 
the FDB 



• GET$S and PUT$S 

Used for sequential access only 

Takes less space than GET$ and PUT$ 

Used only to optimize space in an overlaid task 

• GET$R and PUT$R 

Used for random access only. 
The formats of the macro calls are: 
GET$ f db ,urba ,urbs , err 

GET$S f db , urba ,urbs ,err 

GET$R fdb,urba,urbs,lrcnm, hrcnm, err 



urba and urbs override any previous URB setups 



lrcnm and hrcnm - the low word and high word of 
the record number (random I/O only) 



PUT$ 



f db , nrba ,nrbs,err 



PUT$S 



f db ,nrba,nrbs,err 



PUT$R 



f db f nrba,nrbs f lrcnm, hrcnm ,er r 



nrba and nrbs override the previous settings 
for the next record buffer (NRB) 
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Examples : 

PUT$ #FDB1, , , ERR 

Write the record pointed to by the next record buffer pointer 
into the file at the current location. Use the FDB at FDB1 . 

GET$R ,#MYBUF, #64. ,#93. 

Read record 93(10) into the buffer MYBUF. The buffer length 
is 64(10). R0 contains the FDB address. 



Sequential Access 

For sequential access, use PUT$ and GET$, or PUT$S and GET$S. 
FCS uses internal pointers to identify the record to be operated 
on next. The initial pointer location is at the beginning of the 
file unless the file is opened for Append. In that case, the 
original pointer location is at the end of the file. Each PUT$ or 
GET$ operation sets the pointers to the record after the record 
just accessed. This means that a series of PUT$s or a series of 
GET$s work on successive records. 

To update a record in place, you cannot use a GET$, then 
update the record, and then use a PUT$ . With that seqeunce, the 
GET$ updates the record after the one you read. Instead, use two 
special file control routines, .MARK and .POINT, which allow you 
to save and reset the internal pointers. Use a .MARK before you 
do the GET$, and save the returned pointers to the record. Then 
do a GET$ and update the record. Use a .POINT to reset the 
internal pointers. Finally, issue a PUT$ to update the record. 
See sections 4.10.1 on .POINT, and 4.10.3 on .MARK, in the 
IAS/RSX-11 I/O Operations Reference Manual for details on how to 
use these routines. 

After all GET$ operations, the next record buffer (NRB) 
descriptors identify the address and length of the record just 
read. The address is located at offset F.NRBD+2 in the FDB, and 
the length is at offset F.NRBD. 

For all PUT$ operations, the NRB descriptors identify the 
record to be written. Depending on whether you use move or locate 
mode, as described in the following paragraphs, you may or may not 
need to use the NRB descriptors. 
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In move mode (Figure 10-2) , GET$ operations always move the 
record read to the user specified record buffer. Therefore, in 
general, specify the URB address and size once (in a FDRC$A, 
FDRC$R, or a file open call). Once these are set up, do not 
specify them again unless you want to use a different buffer. 
After each GET$, access the record directly in the URB, which has 
a known address. If you specify a different URB in a GET$ call, 
that becomes the URB for later GET$ calls, unless another URB is 
specified . 

PUT$ operations in move mode (Figure 10-2) assume that the 
record has been built at the location set up in the NRB 
descriptor. This defaults to the URB. Therefore, the easiest 
method is to specify the URB once, and then build all records in 
the URB. Then issue PUT$s without specifying an NRB. 

If you want to build your records in a different buffer, you 
must specify an NRB in the first PUT$ call. After that, for 
successive PUT$s, build all records in the NRB so that you won't 
have to respecify an NRB. If however, you mix GET$s and PUT$s, 
you must specify your NRB in each PUT$ call, because each GET$ 
call updates the NRB descriptors to point to the record just read 
(specifically the NRB pointer points to the URB) . 

In locate mode (Figure 10-2) , you generally access records 
directly in the FSR block buffer. The only time a user record is 
needed is if a record spans block boundaries. Set up a URB only 
if this is a possibility. 

For GET$ operations, the NRB descriptors identify the record 
just read. Access the record at the NRB address (offset 
F.NRBD+2). This pointer points directly into the FSR block buffer 
if the record does not span block buffer boundaries. 

For records which span block buffer boundaries, FCS moves the 
record to the URB and the NRB pointer points to the URB instead of 
a location within the FSR block buffer. Do not specify a new URB 
unless you want to use a different URB for records that span block 
boundaries . 

For PUT$ operations in locate mode (Figure 10-2) , build the 
record at the NRB address. This assumes that the NRB descriptors 
have already been updated to point to the record to be built, 
either by the file open macro, or the previous PUT$ or GET$. Once 
the record is built, use a PUT$ to allow FCS to do some internal 
bookkeeping and update its internal pointers for the next 
operation. 
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In locate mode, be very careful when you write to a file, 
because you are working directly in the FSR block buffer. If you 
build a record in the wrong location by mistake, you cannot easily 
recover any record which gets overwritten. In move mode, on the 
other hand, since you work in a separate URB buffer, a mistake 
discovered before issuing a PUT$ does not update the FSR block 
buffer . 

For both move and locate modes, you can also use the .POINT 
routine to return to the beginning of a file, or the .MARK and 
.POINT routines to save and later return to a record previously 
accessed. This allows a very limited form of random access. 



Random Access 

For random access, use PUT$ and GET$ or PUT$R and GET$R. 
PUT$R and GET$R are easier to use because you can specify the 
record number in the macro call. For random operations, on each 
PUT$ or GET$ call, the record number field in the FDB (offsets 
F.RCNM, high-order word, and F.RCNM+2, low-order word) is used to 
calculate the position of the record to be operated on. 

When the file is opened, the record number is always 
initialized to '1', even if the file is opened for Append. After 
each PUT$ or GET$ operation, the record number is set to one more 
than the last record accessed. You can override this default by 
specifying a record number in a PUT$R or GET$R call, or by 
manually placing the record number directly into the FDB before a 
PUT$ or GET$ call . 

For move mode, the URB and NRB mechanics are exactly the same 
as for sequential access. For locate mode, GET$ operations are 
the same as for sequential access. 

PUT$ operations are very similar. For PUT$ operations in 
locate mode, build the record directly at the NRB address. After 
each PUT$ operation, the NRB pointer is updated to point to the 
record after the record written. Therefore, if you are updating a 
record other than the next record, use either a dummy GET$R call 
or the .POSRC routine to set the NRB pointer to the record to be 
built. See section 4.10.2 on .POSRC in the IAS/RSX-11 
I/O Operation Reference Manual for details on how to use that 
routine . 
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For all types of access, as you do PUT$s to a file, FCS 
transparently extends the file as necessary. 

NOTE 

FCS updates the logical end-of-file 
information in the FDB , but not in the file 
header. Close the file using the CLOSE$ 
macro to write the end-of-file information 
out to the file header. See the next 
section, on closing the file, for additional 
information. 

See sections 3.9 (on GET$) through 3.14 (on PUT$) in the 
IAS/RSx-11 I/O Operation Reference Manual for additional infor- 
mation on performing record I/O . 



Closing the File 

Use the CLOSE$ macro to explicitly close a file, specifying 
the address of the FDB. CLOSE$ performs appropriate cleanup work 
which involves I/O transfers to the file. 

• Waiting for I/O in progress to complete (multiple buffered 
record I/O only) 

• Performing any needed write of the FSR block buffer 
(record I/O only) 

• Updating the file header (high block, end of file block, 
first free byte) . 

Since CLOSE$ performs I/O transfers to the file, always check 
for errors on return to ensure that the transfers were 
successfully performed. If a CLOSE$ is not issued before a task 
exits, the Executive closes the file. If the file was opened with 
write access (write, modify, append, or update), the Executive 
locks the file unless you specify "no lock of files" in the FDOP$A 
or FDOP$R call . 
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Examples of Record I/O 



This section contains several examples which show how to use 
the various FCS services discussed previously for record I/O. 
Also, look back at Example 10-1, our introductory example. It 
shows how to create a file with variable-length records using 
sequential I/O. Examples 10-2 and 10-3 show how to create a file 
with fixed-length records using sequential I/O. Example 10-2 uses 
the assembly-time FDB initialization macros, and Example 10-3 uses 
the run-time FDB initialization macros. Examples 10-1 to 10-3 all 
use move mode. Example 10-4 shows how to read records from an 
existing file using locate mode. Example 10-5 shows how to read 
records from an existing file using random access in move mode. 

Example 10-2 creates the file FIXED. ASC. It takes records 
input at TI : and places them in the file, terminating input and 
closing the file when a "Z is typed. The following notes are 
keyed to Example 10-2. 

Q Symbol for record size. Allows easy modification of the 
record size. 



Q The user record buffer (URB). Input from TI : is read 
into this buffer and then written to the file using PUT$s. 

Q Output buffer, argument block, and format strings for 
generating error messages using $EDMSG. This is for both 
QIO errors and FCS errors. 

Q Allocate FSR space; one FSR block buffer for record I/O. 
The default size is 512(10) bytes. 

Q Assembly-time initialization of FDB. 

Q Open file for write. All FDB parameters are already set. 
The extra ERR1 argument causes a call to the subroutine 
ERR1 in the case of an open error. 

Q Fill the URB with blanks before each read to avoid garbage 
from a previous read, because you will be reusing the 
buffer . 

Q Issue read. Check for directive and I/O errors. Display 
an error message and exit on either type of error using 
common code at SHOERR, except for a "Z. In that case, 
branch to a common exit routine which closes the file and 
exits. 
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Use PUT$ to write the record to the file. FCS takes the 
record at NRB (in this case the same as URB by default) , 
writes it to the file and updates its internal pointers 
for the next PUT$. Call the subroutine ERR2 in the case 
of an error. 

Branch back, clear the URB and read the next input. 

After a ~Z, close the file, check for errors and exit. 
Use BCS here instead of an additional CLOSE$ argument, to 
show that this technique is also possible. The two forms 
are similar. The only difference is that BCS does not 
affect the stack, while the additional argument form uses 
a JSR PC, which pushes the return address onto the stack. 

Error processing, as discussed in the section on Error 
Checking. This code always issues an explicit CLOSE so 
that the file is unlocked. No error occurs if a file 
which is not yet opened, is closed. This code does not 
distinguish whether the error was caused by the OPEN$R, a 
PUT$, or the CLOSE$ call. Additional code can be added to 
tell which call caused the error. 
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6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
*20 
21 
22 
23 
24 
25 
26 
27 
*28 
29 
30 
,31 
*32 
33 
34 
35 
36 
37 
3(3 
.39 
40 
I 41 
42 
r43 
I 44 
45 
L46 



♦TITLE 

♦ I DENT 
♦ENABL 



CREFXA 

/Ol/ 
LC 



Enable lower case 



9 + 

? File CREFXA ♦ MAC 



FIXETuASC for write? inputs records 
puts them seauentially to the file* 



CREFXA opens 
from TI* and 
A ~z terminates input and closes the file* 



RS.TZ 
IGSTI 

print: 

buff: 

obuff: 

arg: 



♦ MCALL 
♦ MCALL 
♦ MCALL 
♦ MCALL 
♦ NLIST 
^ 30* 
*BLKW 
GIOW* 

♦ BLKB 

♦ BLKB 

♦ BLKW 



System macros 
System FCS 
macros 



efdgio * *asciz 
efigio: *asciz 
efcdir: *asciz 
efcsio: *ASCIZ 

♦ EVEN 

♦ LIST 



EXST*C y G I0W*C t GIOW* ? DI R* 
FSRSZ* 9 FDBDF* ? NMBLK* ? 
FDRC*A r FDAT*A y FDGP$A y 
0PEN*W y GET* y PUT* y CLOSE* y 
BEX ? Suppress ASCII 

? Record size (bytes) 
2 9 QIO status block 

10 * WVB y 5 y 1 y y y y <0BUFF y y 40> 
RSIZ 9 User record buffer 

80 ♦ P Output buffer for 

y error messages 
1 ? Argument block for 

9 *EDMSG 

/DIRECTIVE ERROR ON GIG ♦ ERROR CODE 
?I/0 ERROR ON QIO* ERROR CODE ZD*? 
/FCS DIRECTIVE ERROR ♦ ERROR CODE = ZD*/ 
?FCS I/O ERROR* ERROR CODE •= ZD*? 



ZD 



BEX 



y Show offsets 



FSRSZ* 1 9 1 file for record I/O 

FDBJ FDBDF* y File descriptor block 

FDRC*A y BUFF y RSIZ ? User buffer and size? 

y default is record I/O 

y with sequential acces 
FDAT*A R ♦ FIX* FD*CR? RSIZ ? Fixed length records? 

? implied < C R > < L F > 

FD0P*A lyyFILE 9 use LUN 1 

FILE: NMBLK* FIXED yASC ? FIXED*ASC 



start: open*w #fdb 



yyyyyyERRl ? OPEN? if open fails y 

9 CALL ERR1 

CLRBUF: MOV #RSIZyRl 9 Size of URB 

MOV #BUFFyR2 ? Addr of URB 

LOOP: MOVB #' y(R2)+ ? Blank fill record 

SOB Rlyloop ? so no garbage fill 



Example 10-2 Creating a File of Fixed Length Records, 
Initializing FDB at Assembly Time (Sheet 1 of 3) 
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47 




GI0U*C 


IQ*RVB>5» lr »IOST» 


y<BUFF!»RSIZ>» Read 3 




48 






9 


line from TI* 




49 




BCC 


DIROK r 


Branch on Directive ok 




50 




MOV 


♦EFDQIOyRl 5 


Set up for *EDMSG 




51 




MOV 


#*DSW>R2 > 






52 




BR 


SHOERR ? 


Branch to show error 




53 






9 


and exit 




54 


DIROK* 


TSTB 


IOST ? 


Check for I/O error 


e 


55 




BGT 


OKIO f 


Branch if I/O ok 




56 




CMPB 


#IE*EOF*IOST f 


Check for EOF 




57 




BEQ 


EXIT ? 


If- EG* close and exit 




58 




MOVB 


IOST»RO f 


I/O status is sign 




59 






[ 


extended and placed 




60 








111 o I ?3 U III tr 1 1 u L' J. IJ C n. 




61 




MOV 


RO^ARG 9 


for *EDMS6 call 




62 




MOV 


#ARGyR2 i 


Set up for *EDMSG call 




63 




MOV 


♦EFIQIOvRl 9 






64 




BR 


SHOERR 9 


Branch to show error 


o 


65 








and exit 


66 


okio: 


PUT* 


*FDB?y>ERR2 ? 


Write next record 






BR 


CLRBUF 5 


Get next record 


68 












"69 


exit: 


CLOSE* 


#FDB 9 


Close file 


O 


70 




BCS 


ERR3 9 


Branch on FCS error 




.71 

■in 




EXST*C 


EX*SUC 9 


Exit with status of 1 


73 


r Error 


Processing 






"74 


ERR 1 ♦ 










75 


ERR2* 










76 


ERR3 : 


TSTB 


F ♦ ERRf 1 ( RO ) 9 


Directive error or I/O 




77 








error 




78 




BEQ 


10 9 


Branch on I/O error 




79 




MOV 


♦EFCD.TR j»R1 9 


Set up for *EDMSG? 




80 








directive error 




81 




BR 


FINSET 9 


Branch to finish setup 


© 


82 


io: 


MOV 


#EFCSI0?R1 9 


Set up for *EDMSGs» I/O 


83 








error 


84 


finset: 


MOVB 


F»ERR<RO)>RO ? 


FCS error code 




85 




MOV 


RO 9 ARG 9 


is si£n extended and 




86 




MOV 


#ARG»R2 9 


placed in 3rg block 




87 








*EDMSG argument block 




88 


shoerr: 


MOV 


♦OBUFFyRO 9 


Output buffer 




89 




CALL 


*EDMSG 9 


Format error message 




90 




MOV 


RlyPRINT+G,I0PL+2 


9 Size of message 




91 




DIR* 


♦PRINT 9 


Print error message 




92 




CLOSE* 


#FDB 9 


Close file 




_93 




EXST*C 


EX*ERR 9 


Exit with status of 2 


94 




♦ END 


START 
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FILE CONTROL SERVICES 



Run Session* 



>RUN CREFXA 
1 .1. 1 1 1 



333333 
44 

Where did aou sfo? 
6666 66 



Dump of 


DB1 :C30! 


5>3013F.TXED*ASC?. 


4 - 1 


File 


ID 23746 


\9 1 3 


















Kfi rtual 


, bli 


ock 1 


Oy 000001 


- Si 


ze £ 


il2* 


bates 








000000 


061 


061 


061 


061 


061 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000020 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


062 


062 


000040 


062 


062 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000060 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


063 


063 


063 


063 


000100 


063 


063 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000120 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


064 


064 


040 


040 


040 


040 


000140 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000160 


040 


040 


040 


040 


040 


040 


040 


040 


127 


150 


145 


162 


145 


040 


144 


151 


000200 


144 


040 


171 


157 


165 


040 


147 


157 


077 


040 


040 


040 


040 


040 


040 


040 


000220 


040 


040 


040 


040 


040 


040 


066 


066 


066 


066 


040 


066 


066 


040 


040 


040 


000240 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000260 


040 


040 


040 


040 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000300 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 
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FILE CONTROL SERVICES 



Example 10-3 performs the same function as Example 10-2, but 
it uses the run-time FDB initialization macros. The following 
notes are keyed to Example 10-3. 

Q Include the run-time ($R) macros. 

Q At assembly time, simply allocate space for the FDB and 
initialize the default filename block. 

Q Issue the run-time FDB initialization macros, specifying 

the FDB address in the first call. The first call returns 

the FDB address in R0. The subsequent calls default the 
F*DB address to R0. 
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FILE CONTROL SERVICES 



1 ♦ TITLE CREFXR 

2 . 1 DENT /Oil./ 

3 *ENABL LC ? Enable lower esse 

4 5 + 

5 t File CREFXR ♦ MAC 

6 r 

7 ? CREFXR opens FIXED*ASC for write y inputs records 

8 y from TI* and puts them seauential ly to the file* 

9 9 A ~Z terminates input and closes the file* 



10 


f 








11 


r This 


prosfram 


uses the *R macros at run time to 


12 


9 initialize the FDB 




13 










.1.4 




♦ nt/Hi_i«. 


EXST*CrQI0W*C* 


QIOUI*rDIR* y System macros 


_ 15 




MP Al 1 
♦ PI w H L. L. 


FSRSZ* 9 FDBDF* y 


NMBLK* y System FCS 


o 


16 




MCAI 1 - 
♦ DlfHLL 


FDRC*R y FDAT*R 9 


FD0P*R y macros 


17 




- MPAJ 1 
♦ ni>HLL. 


QPEN*W> GET* > PUT* » CLOSE* y 


18 






BEX 


y Suppress ASCII 


19 


RSIZ 


= 30* 




9 Record size (bytes) 


20 


I0ST* 


♦ BLK'U 


2 


y QIO status block 


21 


PRINT ♦ 


QI0W* 


HKWVBvSyly y y y 


<0BUFFr0y40> 


22 


buff: 


♦ BLKB 


RSIZ 


y User Record Buffer 


23 


OBUFF* 


♦ BLKB 


80* 


y Output buffer for 


24 








? error messages 


25 


arg: 


♦ BLKW 


1 


9 Argument block for 


26 








9 *EDMSG 


27 


EFDQIOJ 


*ASCIZ 


/DIRECTIVE ERROR ON 010* ERROR CODE « ZD 


28 


EFIQIOJ 


*ASCIZ 


?I/0 ERROR ON 


QIO ♦ ERROR CODE « ZD*? 


29 


efcdir: 


♦ A S C I Z 


/FCS DIRECTIVE 


ERROR* ERROR CODE = ZD*/ 


30 


EFCSIOJ 


♦ ASCIZ 


?FCS I/O ERROR* ERROR CODE = ZD*? 


31 




♦ EVEN 






32 




♦ LIST 


BEX 


y Show offsets 


33 










34 




FSRSZ* 


1 


? 1 file for record I/O 




FDB : 


FDBDF* 




9 Allocate space for FDE< 


• [£■ 


DFILE5 


NMBLK* 


FIXED? ASC 


9 Default Name Block r 


37 








9 for 'FIXED* ASC 


38 












"39 


start: 


FDAT*R 


#FDB?#R*FIXy#FD*CRy#RSIZ ? Fixed length 




40 








9 records y implied <CR> 




41 








9 <LF> 




42 




FDRC*R 


y y #BUFF y #RSIZ 


y User buffer addr and 


e 


43 
44 
45 








i size* move mode and 
? sequential access by 
9 default 




46 




FD0P*R 


f#lff #DFILE 


i Use LUN 1? Default 




-47 








y Name Block 
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FILE CONTROL SERVICES 



4(3 




OPEN*W 


9 9 9 9 9 9 ERR1 




OPEN ~ if open failsy 


49 










CALL ERR1 


50 


clrbuf: 


MOV 


#RSIZ»R1 




Size of URB 


5.1 




MOV 


#BUFF»R2 




Addr of URB 


52 


loop: 


MOVB 


# ' 9 < R2 ) + 




Blank fill record 


53 




SOB 


RlyLOOP 




so no garbage fill 


54 




QIOW*C 


I0*RVB*5>1> 9 IOST 




?<BUFFy30»> % Read 3 


55 










line from TI* 


56 




BCC 


DIROK 




Branch on Directive ok 


57 




MOV 


#EFDG10 y Rl 




Set up for *EDMSG 


58 




MOV 


#*DSW»R2 






59 




BR 


SHOERR 




Branch to show error 


60 










and exit 


61 


dirok: 


TSTB 


IOST 




Check for I/O error 


62 




BGT 


OK 10 




Branch if I/O ok 


63 




CMPB 


#IE ♦ EOF 9 IOST 




Check for EOF 


64 




BEG 


EXIT 




If EG? close and exit 


65 




MOVB 


lOSTyRO 




I/O status is sign 


66 










extended and placed 


67 










in argument block 


68 




MOV 


ROy ARG 




for *EDMSG call 


69 




MOV 


#ARG y R2 




Set up for $EDMSG call 


70 




MOV 


♦EFIGIQyRl 






71 




BR 


SHOERR 




Branch to show error 


72 










and exit 


73 












74 


okio: 


PUT* 


#FDB 999 ERR2 




Write next record 


75 




BR 


CLRBUF 




Get next record 


76 












77 


EXITJ 


CLOSE* 


#FDB 




Close file 


78 






ERR3 




Branch on FCS error 


79 




EXST*C 


EX*SUC 




Exit with status of 1 


80 












81 


i Error 


Proces 


sing 






82 


ERR1 i 










83 


ERR2 : 










84 


ERR 3 : 


TSTB 


F ♦ ERR+1 ( RO ) 


9 


Directive error or I/O 


85 








9 


error 


86 




BEO 


10 


9 


Branch on I/O error 


87 




MOV 


♦EFCDIR 9 Rl 


9 


Set up for *EDMSGy 


88 








9 


directive error 


89 




BR 


F INSET 


9 


Branch to finish setup 


90 


io: 


MOV 


#EFCS10yRl 


9 


Set up for $EDMSGy I/O 


91 








9 


error 


92 


f inset: 


MOVB 


F*ERR<RO) yRO 


9 


FCS error code 


93 




MOV 


RO 9 ARG 


9 


is sign extended and 


94 




MOV 


*ARG?R2 


9 


placed in arg block 


95 








9 


for *EDMSG 
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FILE CONTROL SERVICES 



96 
97 
98 
99 
100 
101 
102 



SHOERRi MOV 



CLOSE* 
EXST*C 
♦ END 



CALL 

MOV 

DIR* 



#OBUFF * RO y Output buffer 

*EDMSG i Format error message 

Rl yPRINT+Q * IOPL+2 ? Size of message 

♦PRINT 9 Print error messa&e 

#FDB 9 Close file 

EX$ERR 9 Exit with status of 

START 



Run Session 



>RUN CREFXR 
11111 



333333 
44 

Where did you go? 
66 66- 66 



Dump of DDI * C305*3013FIXED* ASC?5 ••- File ID 24564*6*0 









Mi rtual 


, block 1 


0*000001 


™ Si 


,ze ! 


512* 


bytes 








000000 


061 


061 


061 


061 


061 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000020 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


062 


062 


000040 


062 


062 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000060 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


063 


063 


063 


063 


000100 


063 


063 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000120 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


064 


064 


040 


040 


040 


040 


000140 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000160 


040 


040 


040 


040 


040 


040 


040 


040 


127 


150 


145 


162 


145 


040 


144 


151 


000200 


144 


040 


171 


157 


165 


040 


147 


157 


077 


040 


040 


040 


040 


040 


040 


040 


000220 


040 


040 


040 


040 


040 


040 


066 


066 


066 


066 


040 


066 


066 


040 


040 


040 


000240 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


040 


000260 


040 


040 


040 


040 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000300 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 


000 



Example 10-3 Creating a File of Fixed Length Records, 
Initializing FDB at Run Time (Sheet 3 of 3) 



469 



FILE CONTROL SERVICES 



Example 10-4 reads the first five records of the file 
VAR1.ASC (which is created using Example 10-1) and displays them 
at TI : . It uses sequential I/O in locate mode. The following 
notes are keyed to Example 10-4. 

Q FDB allocation and initialization. Specify locate mode; 
default is sequential access. No FDAT$A or FDAT$R macro 
is needed because the file already exists. No user record 
buffer is needed because none of the first five records 
spans block boundaries. None span block boundaries 
because the maximum input record for Example 10-1 is 
80(10) bytes. Specify a URB if records can span block 
boundar ies . 



Q Set up loop counter to read five records. 

Q GET$ a record. The FDB pointer is returned in R0 after 
the OPEN$R call. 

Q Write the record at TI : . The pointer to the record is at 
offset F.NRBD+2 in FDB; size is at offset F.NRBD in FDB. 
No '#' is used because we want to use the contents of 
those locations as arguments. 

Q Decrement the counter and loop back until done. When 
done, close the file and exit. 



:l ♦TITLE READLC 

2 ♦ I DENT /01/ 

3 ♦ENABL. LC y Enable lower case 

4 5 + 

5 y File READLC ♦ MAC 

6 J 

7 y This task reads the first 5 records from the file 

8 y VAR1'»ASC and displays them at the terminal* It uses 

9 ? locate mode* 

10 y~ 

11 ♦ MCALL OPEN*RyGET*»QIOW*S»NMBLK*»FDOP*A 

12 ♦ MCALL CLOSE* y EXI T*S y FDBDF* y FDRC*A y FSRSZ* 
13 

14 FSRSZ*.' 1 y 1 FSR block buffer 

rl5 FDB J FDBDF* 

16 FDRC*A FD.PLC y Locate mode 

17 FDGP*A lyyDFNB $ LUN It default file 

18 \ y name block 
Ll9 DFNBi NMBLK* VARIyASC i File FIXEIUASC 

20 | 

Example 10-4 Accessing a File in Locate Mode (Sheet 1 of 2) 
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FILE CONTROL SERVICES 



21 
22 
23 
24 
25 
26 
27 

I 28 

02? 
30 

| 31 
[32 
33 

* 34 
L35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 



qbuff: 

ARG t 

efcdir: 
efcsio: 

start: 



.OOP* 



y Error 
ERRC t 

errr: 

ERRO J 



ioerr: 

F INSET 



♦ BLKW 

♦ BLKW 
♦ASCIZ 
♦ASCIZ 

♦ EVEN 
GPEN*R 
BCS 
MOM 
GET* 
BCS 

QIOU*S 

SOB 

CLOSE* 
BCS 

EXIT*S 
code 



TSTB 

BE Q 

MOV 

BR 

MOV 

MOVB 

MOV 

MOV 

MOV 

CALL 

QIOW*S 

CLOSE* 
EXIT*S 
♦ END 



80 ♦ ? Error message? buffer 

1 y * EDM SO argument block 

/FCS DIRECTIVE ERROR ♦ ERROR CODE = ZD./ 
'FCS I/O ERROR* ERROR CODE = %D*' 



#FDB 
ERRO 
#5 1 R2 

ERRR 

#IG*WVBy#5y#l 
R2yL00P 

ERRC 



F.ERR+KRO) 
IOERR 

#EFCDIRvR.1. 
F INSET 
#EFCSIOyRl 
F ♦ ERR ( RO ) y RO 
RO y ARG 
#ARG y R2 
#OBUFFyRO 
*EDMSG 

#I0*WVBy#5y#ly 

#FDB 

START 



y Open file for read 

y Branch on FCS error 

? Loop counter 

y Get record 

y Branch on error 

y <FDB+F ♦ NRBD+2 1 FDB+F ♦ NRBD » #40!: 

y Decrement loop counter 

y Close file 

y Branch on error 

y Exit 



y Directive error or I/O 
y error? 

y Branch on I/O error 

y Set up for * ED MSG 

y Branch to display code 

y Set up for *EDMSG 

y Si an extend FCS error 
y code and place in 
y a r si u m e n t b I o c k 

? Output buffer 

y Format error message 
y y y <#0BUFF y R 1 y #40> y W r i te 
y message 

y Close file 

y Exit 



Run Session 

>RUN READLC 
1111 

22222 22 
333 

JAZZ Jazz JAZZ Jazz 

Have you ever seen the sun? 



Example 10-4 Accessing a File in Locate Mode (Sheet 2 of 2) 
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FILE CONTROL SERVICES 



Example 10-5 uses random access to read records from the file 

FIXED. ASC, which is created using either Example 10-2 or Example 

10-3. It prompts at TI : for a record number and displays that 

record at TI : . The following notes are keyed to Example 10-5. 

O FCSMC$ is a macro containing . MCALLs for most of the FCS 

macros. Using it can avoid having to specify all of the 

FCS macros in .MCALL statements. Note that GET$R is not 
included in FCSMC$, so it is specified separately. 

Q Using the $ form of all QIOs . With the exception of the 
QIO at PRINT, all parameters are set at assembly time. 
Therefore, any of the three forms ($, $C , or $S) can be 
used for the QIOs at ECHO, PROMPT, and WARN. Either the $ 
or the $S can be used for the QIO setup at PRINT. 



Q The record number is input in ASCII (up to two digits) . 
Q FDB for file. Use random access I/O. 

Q Open file for read. Prompt for and read record number. 

Q On a directive error, use the supplied macro DIRERR to 
display an error message and the DSW , and then exit. 

Q Check for I/O error. If the error was a ~Z, branch to 

EXIT to close the file and exit. If any other error 

occurred, use the supplied macro IOERR to display an error 
message and the IOSB, and then exit. 

Q Set up and call .DD2CT to convert the record number from 
ASCII to double-precision binary. During setup, make sure 
that at least one digit was input. If none were input, 
prompt again. Double precision is used only to show how 
to take advantage of the full range of record numbers (up 
to 31 bits in two words) . 

Q Move the low-order 16 bits of the record number to R2, and 
use GET$R to read the record. Call the subroutine ERR2 on 
any FCS error. Only the low-order 16 bits are needed, 
because we know the record number is less than or equal to 
99(10). 

Q Display the record and prompt for the next record number. 
Always display 30(10) characters, because the file has 
fixed-length records. 
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Q On FCS errors, first check for end-of-file. If it is not, 
branch to common FCS error code at ERR3. If the error is 
read past end-of-file, display a warning message and 
prompt for the next input. Because this routine is 
entered with a JSR PC instruction, you must clear the 
return address off the stack before using a BR 
instruction . 

Notice that the supplied macros DIRERR and IOERR are, used for 
QIO errors, but not for FCS errors. This is because FCS returns 
error status to the FDB . In fact, DIRERR would work correctly 
because the DSW is returned by the Executive, and FCS moves the 
DSW value into the FDB. IOERR however, does not work correctly 
because FCS sets up its own internal I/O status block, and its 
address is not available to the user task. The supplied macro 
FCSERR is set up to handle both types of FCS errors. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 

26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 



♦TITLE RANDOM 
♦I DENT /Ol/ 
♦ENABL LC 



? Enable lower esse 



File RANDOM* MAC 



RANDOM uses direct access to a file? FIXED *ASCy which 
contains fixed length records* This task prompts at 
TI* for a record number* and displays it at TI* 
It exits when a control Z is input 

A s s e m b 1 e a n d t a s k - b u i 1 d i n s t r u c t i o n s * 

>macro/l:i:st lb : c 1 > 1 uprogmacs/library ? dev : cuf <n~ 

•~>RAND0M 

>L INK/MAP RANDOM ?LB* CI * 1 3PR0GSUBS/L IBRARY 



ECHO J 
PR MPT * 

warn: 
print: 



♦MCALL 
* MCALL 

♦MCALL 
FCSMC* 
♦ NLIST 
OCAL DATA 
RSIZ 
GIOW* 
QIOW* 
QIOW* 
QIOW* 



QIOW*yDIR*yEXIT*SyGET*R t System macros 
y Macro to get most 
i system FCS macros 
y Supplied macros 
9 Get most FCS macros 
t Supress ASCII 



FCSMC* 

DIRERR 9 10ERR 
BEX 

-30. y Record size 

1 ♦ WMB r 5rlMM <BUFF y 30 ♦ y 40> 

1 ♦ RPR y 5 y 1 y t I OST t t < AREC y 2 y y MES 1 9 S I Z 1 y ' *> 
1 ♦ WVB y 5 y 1 1 t t y <MES3 y S I Z3 y 40> 
1 ♦ W YB y 5 y 1 y y y y <0UT y 9 40> 



buff: 

I OST J 

arec: 
rec : 
out: 

mesi: 

MES2: 
MES3: 

efcdir: 
efcsio: 



♦ BLKB 

♦ BLKW 

♦ BLKW 

♦ BLKW 

♦ BLKB 

♦ASCII 

SIZ1 = 

♦ASCIZ 

♦ASCII 

SIZ3 

♦ ASCIZ 

♦ASCIZ 

♦ EVEN 



RSIZ 
':> 

1 
':> 

100. 



User record buffer 
I/O s t a t u s b I o c k 
Record number in ASCII 
Record number in binary 
* E D M S G outp u t b u f f e r 



/RECORD NUMBER?/ 
♦ -MESI 

/FCS ERROR* ERROR CODE = ZD*/ 
/***PAST END OF FILE***/ 
♦ -MES3 

/FCS DIRECTIVE ERROR ♦ CODE « ZD./ 
' FCS I/O ERROR* CODE = ZD* ' 



Example 10-5 Accessing a File in Random Mode 

(Sheet 1 of 3) 
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46 
47 
r 48 
49 
50 
51 
52 
53 
54 
55 
56 
' 57 
58 
59 
1-60 
61 
62 
63' 
[64 
I 65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
r-77 
L 78 
[-79 
L 80 
81 
82 
"83 
84 
.85 
86 
'87 
88 
89 
90 
91 
92 
93 
94 



FSRSZ* 1 5 1 file opened for 

y record I/O 

FDBi FDBDF* y File descriptor block 

FDRC*A FD * RAN y BUFF y RSI Z y Random access? URB 

9 sddr and size 



FD0P*A 1 9 y FILE 
F I LE * N M B I... K * F I X E B y A S C 

♦ENABL I... SB 
START ♦ 0PEN*R #FBB 999999 ERR1 



10*: 



DIR* 



♦PRMPT 



9 Use LUN ly default 
9 name block at FILE 

9 Default name ~ 
9 FIXED»ASC 



v Open file for read 
? CALL ERR1 on open 
9 error 

9 Prompt for record 
9 number 

9 Branch on dir ok 



DIROK i 



9 Check for I/O error 
9 Branch on error 



BCC DIROK 
DIRERR <ERR0R ON QI0> 
TSTB I0ST 
BLT ERR II 

y Convert ASCII record number to double-worded decimal 

9 # of characters to 
9 convert 
y If no characters y 
9 prompt a<3a in 



MOV 

BEQ 

MOV 

MOV 

CALL 

MOV 

GET*R 

DIR* 

BR 



I0ST+2»R4 

10* 

#ARECyR5 
#REC y R3 
♦DD2CT 
REC+2yR2 



9 Address of ASCII 
9 characters 

9 Buffer to store 
9 converted number 

9 Convert ASCII to 
9 decimal 

9 Move low order 16 bits 

♦FDBy y yR2y ?ERR2 y Get specified record 

♦ECHO 9 Print it on Tit 

10* 9 Prompt for next input 



9 ~Z? 

9 If yesy branch to EXIT 



9 ERROR ROUTINES 
ERR 1 1 1 CMPB # I E ♦ EOF 9 1 OST 

BEQ EXIT 

10 ERR #I0STy<ERR0R ON QI0> 
5 Here for errors on GET* 

ERR 2 i CMPB # I E * EOF y F ♦ ERR ( RO ) y Was the error an EOF? 
BNE ERR1 9 Noy it is another 

9 error* branch to ERR1 
? Just display a warning for end of file 

DIR* #WARN y Display EOF message 

TST <SP)+ y Clean off return addr 

9 from stack 
BR 10* 9 Prompt for newt input 
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95 ERR 3 ♦ 

96 ERRi: MOVB F»ERR(R0)»R5 9 Extend sisfn on error 

97 MOM R5j>I'0ST 9 code and move into 

98 MOV *I0STrR2 9 argument block 

99 TSTB F.ERR+KRO) 9 I/O or directive error? 

100 BEQ I0ERR 9 Branch on I/O error 

101 MOV fEFCDIRrRl 9 Directive error message 

102 BR DSPERR 9 Branch to display code 

103 IOERR: MOV #EFCSIOyRl 9 I/O error message 

104 DSPERR t MOV #0UT»R0 9 Output buffer 

105 CALL *EDMSG 9 Edit ouput message 

106 MOV Rl*PRINT+Q*I0PL+2 9 Length of error 

107 9 message 

108 DIR* #PRINT 9 Print error message 

109 CLOSE* #FDB 9 Close file 

110 EXIT*S 9 EXIT 

"111 EXIT: CLOSE* #FDB?ERR3 9 Close file 

112 EXIT*S 9 Exit 

.113 .END START 



Run Session? 

>RUN RANDOM 
RECORD NUMBER?! 
:l. 1 1. 1 1 

RECORD NUMBER?3 
333333 

RECORD NUMBER? 9 
*#*PAST END OF FILE*** 
RECORD NUMBER? 5 
Where did you do? 

> 
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PERFORMING BLOCK I/O 



READS and WRITES Calls 



The formats of the READ$ and WRITE$ calls are: 

READ$ fdb ,bkda ,bkds ,bkvb ,bkef,bkst,bkdn,err 
WRITE$ fdb ,bkda ,bkds ,bkvb , bkef , bkst ,bkdn ,er r 



All parameters except fdb and err override any previous FDB 
settings. Always use a user specified buffer, which can be 
specified in a FDBK$A, or FDBK$R call, an open call, or in a READ$ 
or WRITE$ call. 

The length of the transfer is controlled by the bkds 
parameter. The starting virtual block number in the FDB is 
initially set to 1, unless the file is opened for Append. FCS 
updates the block number after each operation to point to the 
block after the last one accessed. To override the default block 
number, set up a two-word data block for the virtual block number 
and specify the address of the block in a FDBK$R macro call (after 
the file is opened) , or in a READ$ or WRITE$ macro call. 

The following piece of skeletal code shows how to use block 
5, then block 12(10), and finally block 13(10). 

BLCKNM: .WORD 0,5 ; Starting block number 



OPEN$R #FDB 
BCS ERR1 



Open file 



READ$ 



#FDB 



#B LCKNM 



ERR2 



Read block 5 



MOV 
READ$ 



#12. 

#FDB 



• i 



BLCKNM+2 
,#B LCKNM 



Update block # 
ERR3 ; Read virtual 
; block 12(10) 



READ$ 



#FDB 



i i i i i i 



ERR4 



Read next virtual block 
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Unlike record I/O, for block I/O each READ$ or WRITE$ causes 
an I/O transfer between the user buffer and the file. 



Synchronization and Error Checking 

For block I/O, FCS issues asynchronous QIO directives. You 
must provide synchronization and check for both directive and I/O 
errors. Use an event flag or an AST routine for synchronization. 
Check for errors on return from the READ$ or WRITE$ call (after 
the QIO directive is issued) . 

Also check for I/O errors after the I/O operation completes. 
To get I/O error indications, you must set up and specify an I/O 
status block. Otherwise, no I/O status conditions are returned, 
and success must be assumed. 

If you use an AST routine for synchronization, check the IOSB 
directly for I/O errors. If you use an event flag for 
synchronization, use a WAIT$ call to wait for the flag to be set, 
rather than a Wait for Single Event Flag (WTSE$) directive. With 
WAIT$, FCS returns its standard error indications. This means the 
carry bit is clear for success and set for an I/O error. In 
addition, for errors, the I/O error code is returned at offset 
F.ERR in the FDB . If you use the Wait for Single Event Flag 
directive (WTSE$) instead, standard FCS error codes are not 
returned. In that case, you must check the IOSB directly 
yourself. 

See sections 3.15 (on READ$) , 3.16 (on WRITE$), and 3.17 (on 
WAIT$) for additional information about block I/O calls, 
synchronization, and error checking. 

Examples 10-6 and 10-7 show how to use block I/O. Example 
10-6 creates a file BLOCK. ASC using block I/O. Example 10-7 reads 
a virtual block from the file BLOCK. ASC and displays it at TI : . 
The following notes are keyed to Example 10-6. 

You still need an FSRSZ$ statement to set up an FCS, but 
no FSR block buffers are needed. 

FDB setup. FDAT$A and FDOP$A are the same as for record 
I/O. The only difference here is that a dataset 
descriptor is used instead of a default filename block. 
This is done just to show the use of a dataset descriptor. 
FDRC$A specifies read/write mode (block I/O). FDBK$A 
specifies the address and size of the user buffer, the 
event flag for synchronization, and the IOSB address. 
Don't specify the address of the block number until after 
opening the file. 
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Other data structures: A two-word block for the virtual 
block number, initially set to virtual block 1; the user 
buffer, and the I/O status block. 

Prompt for and read virtual block number. "Low only" 
means only a one-word virtual block number, rather than a 
two-word value. 

Place a terminating null character at the end of the ASCII 
virtual block number to set up for a call to $CDTB. Use 
$CDTB to convert ASCII decimal to binary. There is no 
error check included, but it can be added. 

Move the converted virtual block number to the virtual 
block number block. 

Prompt for and get a character to place in the block. 
Fill the user buffer with the character. 
Open (create) the file. 

Start the I/O transfer. Specify the address of the 
virtual block now, since the "open" call initializes the 
block number to 1. 

Display the message and wait for the I/O transfer to 
complete. Using WAIT$, FCS returns its standard error 
indications. Call subroutine ERR3 in the case of an 
error. 

Close the file. 

Set up to display the number of characters transferred, 
branch to common code to edit and display the message, and 
then exit. The code is common to the error message code. 

Common error code. Set up for an I/O or directive error 
message. Set up to exit with error status. 

Common code for displaying a message, closing the file, 
and exiting. In the case of a successful write, you end 
up calling CLOSE$ twice. There is no error for closing 
the file after it is already closed. Use of the common 
code saves space in the task. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
"33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
.43 
*44 
"45 
46 
.47 
48 
49 
50 
51 



♦ TITLE BL0CK1 
♦IDENT /Ol/ 
♦ENABL LC 



i Enable lower case 



? File BLOCK! ♦ MAC 



BLOCK! creates 3 file BLOCK*ASC and fills the specified 
virtual block of the file with the specified character* 
It uses block I/O* 

♦ MCALL QI0W*yDIR**QI0W*S*EXST*S 9 System macros 

♦ MCALL FDBDF* t FDRC*A t FDBK*A * FDQP*A t NMBLK* 

♦ MCALL FDAT*A t FSRSZ* r 0PEN*W t WR I TE* * WAIT* t CLOSE* 



MES1 : 
LEN1 
MES2 : 
LEN2- 
ME S3 : 
LEN3 
MES4 ♦ 

MESD * 

mesi: 

CHAR J 
BUFF ♦ 



FDBi 



DSPT : 



NAM * 
LNAM 

vbn: 

BLOCK * 

iosb: 

TYPE! * 
TYPE2 * 
TYPE 3 ♦ 



♦NLIST BEX 

♦ASCII /VIRTUAL BLOCK NUMBER (LOW ONLY): / 
~ ♦ — MESI 

♦ascii /character: / 

♦ - MES2 

♦ASCII /l BLOCK BEING WRITTEN TO FILE/ 
~ ♦ -- MES3 

♦ ASCII /WRITE COMPLETED v ZD BYTES WRITTEN TO / 
♦ASCIZ /FILE/ 

♦ ASCIZ /FCS DIRECTIVE ERROR 9 CODE = "AH*/ 
♦ASCIZ 'FCS I/O ERROR , CODE * ZD.' 



♦ BLKB 

♦ BLKB 

♦ LIST 

♦ EVEN 
FSRSZ* 

FDBDF* 
FDAT*A 
FDRC*A 
FDBK*A 

FDOP*A 

♦ WORD 

♦ WORD 
. WORD 
♦ASCII 
==*-NAM 

♦ EVEN 

♦ WORD 

♦ BLKW 

♦ BLKW 

QIOW* 
QIOW* 

QIOW* 



1 

100* 
BLX 





R*VAR*FD»FTN 
FD*RWM 

BLOCK? 51 2* 9 9 1 

1 9 DSPT 

0*0 

0*0 

LNAM 9 NAM 
/BLOCK *ASC/ 



0*1 
256* 

1 



9 Character to write 
9 Buffer for *EDMS6 



9 No FSR block buffers 
9 needed for block I/O 
9 Reserve FDB space 
9 File characteristics 
9 Read/write mode 
IOSB 9 MV9 size of buffer* 

* ef 1* IOSB addr 

* LUN 1* DSPT 

* Length and addr of 
and addr of 
and addr of 



9 Length 
9 Length 
9 File name and type 



device 
UIC 
name 



9 Default VBN 

* User buffer 

* I/O status block 



I0»RPR*5»1* *I0SBy *<BUFF*6* *MES1*LEN1* '*! 
10 ♦ RPR 9 5 * 1 * 9 9 9 <CHAR * 1 * 9 MES2 * LEN2 * ' *> 
10 ♦ WVB * 5 * 2 * * 9 9 <MES3 * LEN3 * 40> 
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O 

e 
o 



Code 



St 



53 
54 
55 
56 
57 
53 
059 
60 
61 
62 
63 
64 
65 

©67 

68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
37 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
L98 



START* 


DIR* 


#TYPE1 




9 


Prompt and get VBN 




MOV 


I0SB+2yR0 




y 


Length in RO 




CLRB 


BUFF ( RO ) 




9 


P u t null byte at end 




MOV 


♦BUFFyRO 




9 


RO => ASCII digits 




CALL 


*CDTB 




9 


Convert to binary 




MOV 


RlyVBN+2 




y 


Store as low VBN 




DIR* 


#TYPE2 




9 


Input character 


y Fill 


user buffer with character 






MOV 


♦BLOCK yRO 




9 


Get address 




nOv 


#512 ♦ y Rl 




9 


and size of user buffer 


1 0$ * 


MQVB 


CHARy <R0) + 




9 


Move character 




r* n t*i 

SOB 


Rl y 10* 




<> 


Loop back until done 


5 Open 


f i 1 e to 


receive characters 


y write virtual block 




Ur tMSW 


#FDB y y y y y y ERR1 


9 


Qpeny ERR1 if no good 






y y y#VBNy y y y 


ERR2 


y 


Start transfer 




DIR* 


#TYPE3 




y 


Say transfer started 




WAIT* 


y y y ERR3 




9 


Wait until it's done 




CLOSE* 


y ERR4 




9 


C 1 ose file 




MOV 


#MES4yRl 




9 


Arfr* nf f*fimp 1 P»t i on 

1 1 *„l | \.l | \.. L./ ill! tit G7 W W 1 1 










9 


tTi m a ni <if tok 




MOV 


#EX*SUCyR5 




9 


E x i t statu s 




BR 


FORMAT 




9 


Rranrh + n rnmninn code 

JL' 1 O 1 IUI 1 w w l» W III III W II l« W -J 1m 










9 


f nr iTi f- <z c; si cs a ri i P 1 

1 W 1 111 W t*> H> O C7 'mI J* aM* ? •!- H> 










9 


and exit 


ERR1 i 




































ERR4 ♦ 


TSTB 


F*ERR+1 (RO) 




9 


Directive or I/O error? 




BE a 


I0ERR 




9 


1-f r> r*i r* h nn T / fl orrnr 




MOV 


#MESDyRl 




9 


-~ ■;• T / fl prrflf ITi p„ c; c< c» 

J. / w l» 1 1 w 1 III W .3 ~> O .V3 V. 




BR 


FCSSET 




9 


Ft r* r*i r* !"i + r. r* n iti iti n ri rnrip 


mi- pp ♦ 


MOV 


•tMESI yRl 




9 


~ '■> Hi r prrnp iti p> <■» s 3 <3 e 

.• JL. 1 J, | Cv | 1 I./ 1 III C7 — ' It* ..J w 


rreccT ♦ 
r i.-Oi.)l i ♦ 


MOVB 


F*ERR(R0) yR4 


9 


Ci {(ri f-v+e-riH prrnr rnrip 

w J. *~> 1 1 CT / % w w 1 1 '~l I.. 1 1 W 1 w ••• V.V 




MOV 


R4yI0SB+2 




9 


Use 1/0 status block 










9 


for arg block 




MOV 


*EX*ERRy R5 




9 


Exit status to R5 


y Print 


message y exit with 


status 


in R5 


FORMAT * 














MOV 


#I0SB+2»R2 




9 


R2 -~> 1/0 status 




MOV 


#BUFF y RO 




9 


R0 «> *EDMSG buffer 




CALL 


*EDMSG 




9 


Format the text 




QI0W*S 


#I0*WVBy#5y 


#2y y y 


9 


<#BUFFyRl y#40>5 And 










9 


write it out to Tit 




CLOSE* 


#FDB 




9 


Close file and 




EXST*S 


R5 




9 


Exit with status 




♦ END 


START 
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Run Session 
>RUN BLOCK 1 

VIRTUAL BLOCK NUMBER (LOU) ONLY ) * 2 
CHARACTER *> e 

.1. BLOCK BEING WRITTEN TO FILE 

WRITE COMPLETED? 512 BYTES WRITTEN TO FILE 



Dump of DR2:C305>3013BLOCK*ASCJ10 -• File ID 37355*2 »0 

Virtual block 0» OOOOOl'- Size 512 ♦ bytes 
Contains whatever was previously in that block on the disk 

Dump of DR2:C305»3013BL0CK.ASC?10 - File ID 37355 »2>0 

Virtual block Oy 000002 •••• Size 512* bytes 
000000 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 
000020 145 145 145 145 145 145 145 145 145 145 145 145 145 .1.45 145 145 
000040 145 145 145 145 145 145 145 145 145 .1.45 145 145 145 145 145 145 



000740 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 
000760 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 

*** EOF *** 

Example 10-6 Creating a File With Block I/O (Sheet 3 of 3) 
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Example 10-7 prompts at TI : for a virtual block number, and 
then reads and displays that block of BLOCK. ASC. The following 
notes are keyed to the example. 

Q This example displays, in addition to the error codes, 
text error messages which tell the user which FCS call 
caused the error. 

Q No FSR block buffers are needed for block I/O. 

Q This is the FDB setup. Use read/write mode. Use FDBK$A 
to specify the user buffer address and size, the event 
flag, and the IOSB address. 

Q Open the file for read and prompt for the virtual block 
n urn be r . 

Q Place a null byte at the end of block number for a call to 
$CDTB. Use $ CDTB to convert the block number from ASCII 
decimal to binary. 

Q Store the result, returned in Rl by $C DTB , in the low byte 
of the virtual block number block. 

Issue a READ$ to read the specified block, and use WAIT$ 
to wait for the I/O operation to complete. READ$ and 
WAIT$ return standard FCS status and error returns. 

Q Display a heading and the virtual block. 

Q Close the file and exit. 

© Error code to display the text message, including the 
error code for each type of error. 
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4 

5 
6 
7 
8 
9 
.10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
L40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



♦TITLE BL0CK2 
♦ I DENT /Ol/ 
♦ENABL LC 



J Enable lower case 



y + 

9 File BL0CK2*MAC 



BL0CK2 prompts 3t Tli for 3 virtual block number 

and then reads and displays that block of " BLOCK *ASC 

♦ MCALL Q I0W* y DIR* t QI0W*S t EXST*S .» EXIT*S 

♦ MCALL FDBDF* t FDRC*A r FDBK*A t FD0P*A r NMBLK* 

* MCALL FSRSZ* y 0PEN*R t READS y WAITS y CLOSE* 



CR 
LF 

mesi: 

LEN1 
MES2J 
LEN2 
MES3IJ 
MES3D : 
MES4I: 
MES4DJ 
MES5I : 
MES5D: 
MES6I ♦ 
MES6D ♦ 
BUFF? 



FDB: 



FILE: 
VBNi 

block: 
iosb: 



NLIS' 
= 15 
- 12 

ASCI 

: t — 

ASCI 
: ♦ ™ 
ASCI 
ASCI 
ASCI 
• A S(w X 
ASCI 
ASCI 
ASCI 
ASCI 
BLKB 



BEX 



/ 



/<crxlf: 



« ZD*/ 



I /VIRTUAL BLOCK NUMBER J 
MESI 

I < C R > < L F > / H E R E IS THE BLOCK 
MES2 

Z 'I/O ERROR ON OPENsRy CODE •> 
/DIRECTIVE ERROR ON OPEN*Ry 
'I/O ERROR ON READS y CODE ~ 
/DIRECTIVE ERROR ON READS y CODE - ZD*/ 
' I/O ERROR AFTER WAIT** CODE = ZD*' 
/DIRECTIVE ERROR AFTER WAIT*y CODE * ZD*/ 
'I/O ERROR ON CLOSE* y CODE « ZD*' 

ERROR ON CLOSE* y CODE ZD*/ 
y *EDMSG output buffer 



■ ZD * 

CODE 
ZD* ' 



/DIRECTIVE 
80, 



♦ LIST 

♦ EVEN 
FSRSZ* 

FDBDF* 
FDRC*A 
FDBK*A 

FDOP*A 
NMBLK* 

♦ WORD 

♦ BLKW 

♦ BLKW 



BEX 



FD ♦ RWM 

BLOCK y 512* y yly IOSB 
y 

1 y yFILE 
BLOCK y ASC 

Oyl 
256* 



No FSR black buffer 

needed far block I/O 
FDB for input file 
Read/write mode 

Buffer ad ry sizey 
ef ly iosb 3dr 
LUN ly DFNB 
Name is BLOCK* ASC 



y\ Default VBN 
y User buffer 
y IOSB 



PROMPT? QIOW* 
done: QIOW* 
dump: qiow* 



1 * RPR y 5 y 1 y y I OSB y y <BUFF y 6 y y MES 1 1 LEN 1 y ' *> 

y Prompt and 3et VB # 
I0*WVBy5ylyyyy <MES2 y LEN2 y 40> y Done 

y message 

I0*WVBy5y 1 y y y y<0y64* y40> y Display of VB 
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\J J. 


v Code 












START ♦ 










r.r-7 
JO 




0PEN*R 


♦FDBy ihj yERRl 


y 


Open file 


cr a 
_ J*) 




DIRifc 


♦PROMPT 


y 


Ask for a MBN 


55 




M0U 


IQSB+2yR0 


y 


Put null at end 


cr / 




CLRB 


BUFF(RO) 


y 


of digit string 


57 




mom 


♦BUFFyRO 


y 


RO MBN 


L 58 




CALL 


*CDTB 


y 


Convert to binary 


59 




MOM 


Rl y MBN-f 2 


y 


Store as low MBN 


60 




READ* 


♦FDBy 9 y^MBNy y y y 


ERR2 5 Read in the block 


61 




WAIT* 


9 9 9 ERR3 


y 


Wait until done 


62 




DIR* 


♦DONE 


y 


Tell them I/O is done 


63 


? Now dump 8 lines of 64* characters each 


,■■ j* 

64 




MOM 


♦BLOCK yRO 


y 


RO => 1st line to dump 


jt cr 
OJ 




MOM 


♦8 ♦ yRl 


y 


♦ of lines to dump 


66 


1 $ ♦ 


MOM 


RO 9 DUrlr +Q ♦lurL 


y 


Addr of current line 


a/ 




DIR* 


♦ DUMP 


y 


Dump it 


JL O 
OD 




ADD 


♦64 ♦ yRO 


y 


Point at next line 


_ 69 




SOB 


R 1 9 1 * 


y 


Dump all 8* lines 


70 




CLOSE* 


♦FDByERR4 


y 


Close file 


71 

72 


5 Error 


EXIT*S 
code 




y 


Exit 


73 


ERR1 i 










74 




TSTB 


F*ERR+1 (RO) 


y 


I/O or directive error? 


"7 cr 

/D 




BEQ 


IOERRI 


y 


Branch on I/O error 


76 




MOM 


♦MES3DyRl 


y 


=> Dir error message 3 


77 




BR 


FCSERR 


y 


Branch to common code 


78 


ioerri: 


MOM 


♦MES3IyRl 


y 


~> I/O error message 3 


70 




BR 


FCSERR 


y 


Branch to common code 


80 


ERR 2: 










8.1. 




TSTB 


F*ERR+1(R0) 


y 


I/O or directive error? 


82 




BEQ 


I0ERR2 


y 


Branch on I/O error 


83 




MOM 


♦MES4D yRl 


y 


=> Dir error message 4 


84 




BR 


FCSERR 


y 


Branch to common code 


85 


I0ERR2* 


MOM 


♦MES4IyRl 


y 


~> I/O error message 4 


86 




BR 


FCSERR 


9 


Branch to common code 


87 


ERR3* 










o a 
oo 




TSTB 


F»ERR+1 (RO) 


9 


I/O or directive error? 


89 




BEQ 


1 E R R 3 


9 


Branch on I/O error 


90 




MOM 


♦MESSDyRl 


9 


••=> Dir error message 5 


91 




BR 


FCSERR 


9 


Branch to common code 


92 


I0ERR3 ♦ 


MOM 


♦MESSIyRl 


9 


=> I/O error message 5 


93 




BR 


FCSERR 


9 


Branch to common code 


94 


ERR 41 










95 




TSTB 


F.ERR-fl(RO) 


9 


I/O or directive error? 


96 




BEQ 


I0ERR4 


9 


Branch on I/O error 


97 




MOM 


♦MES6DyRl 


9 


=> Dir error message 6 


98 




BR 


FCSERR 


9 


Branch to common code 


99 


10ERR4: 


MOM 


♦MES6IyRl 


9 


-> I/O error message 6y 


100 








9 


fall into common code 
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FILE CONTROL SERVICES 



101 

102 

103 
104 
105 
106 
107 
108 
109 
110 
1 1 1 
112 
"1 1 3 



"CSERR i 



FORMAT i 



MOVB 

MOV 

MOV 

MOV 
MOV 
CALL 
QIOW*S 

CLOSE* 
EXST*S 
♦ ENIJ 



F»ERR<RO) ?R2 ? 

R2*I0SB 9 

#EX$ERRyR5 ? 

#I0SB»R2 9 

#BUFF»RO 9 

*EDMSG 9 
#I0*WVB»#5»#lf r 9 9- 



#FBB 

R5 

START 



Sign extend error code 

and move into IOSB 
Exit status in R5 

Set up for $EDMSG 



:#BUFF>Ri»#40> i 

message 
Close the file 
Exit with status 



DlSF>l3» 



Run Session 

>RUN BL0CK2 
VIRTUAL BLOCK: 2 

HERE IS THE BLOCK t 

eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee 
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee 
eeefjeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee 
<•>? e e e e © e e e e © e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e 
(•: > © e e © e e e e e e © e e e e e e e e eeeeeeee e e e e e e © e e e eeeeeeeeeeeeeeeeeeeeeeeeee 
e e e © e e e e e © e e e © © © e e e e e e e e e e eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee 
e e e © © © © e e e e e e e e e e e e © e e e e © e e e eeeeeeeeeeeeeeeeeeeeeeeeee ©eeeeeeee© 
e © e e © © © © © e e & © © e e e © e e e e © © © e © e e © e e © e © © e e e e e © © © © © © © © e © © © © © e © © © © e © © e 



Example 10-7 Reading a File With Block I/O (Sheet 3 of 3) 



486 



FILE CONTROL SERVICES 



ADDITIONAL TOPICS 
Deleting a File 

Use the DELET$ macro to delete a file. If the file is open, 
DELET$ closes the file and then deletes it. If the file is 
closed, DELET$ just deletes the file. The format of the DELET$ 
call is: 

DELET$ fdb,err 
DELET$ FDB3 

NOTE 

Unlike the DCL DELETE command, if no version 
is specified, the latest version of the file 
is deleted. 



File Control Routines 

You can use a number of internal FCS routines in your task. 
Some of the available functions include: 

• Filling in an FDB filename block from a dataset descriptor 
or default filename block. 

• Finding, inserting, or deleting a directory entry. 

• Marking a place in a file for later return. 

• Setting a pointer to a byte within a virtual block, or to 
the start of a record in a file. 

• Renaming, extending or truncating a file. 

• Marking a temporary file for deletion, or deleting a file 
by FDB filename block. 

We have already discussed the use of the routines .MARK and 
.POINT for marking a place in a file so that you can later return 
to it, and .POSRC for locating a record with random access in 
locate mode. See Chapter 4 of the IAS/RSX-11 I/O Operations 
Reference Manual for a description of each of the file control 
routines , plus Information on how to use them. 



487 



FILE CONTROL SERVICES 



Command Line Processing 

You can use two other collections of routines to facilitate 
input and processing of command lines, which are useful in general 
or utility tasks. The routines and their functions are: 

• Get Command Line (GCML) 

Performs command line input operations (issues 
prompts, gets input) 

• Command String Interpreter (CSI) 

Parses the file specification in a command line from 
GCML into a dataset descriptor, for use by FCS 

Parses and processes any switches and switch values in 
the command line. 

See Chapter 6 on Command Line Processing in the 
IAS/RSX-11 Operations Reference Manual for a description of the 
command line processing routines. The program CSI. MAC should be 
available on-line (under UFD [202,1]) . It is also listed in 
Appendix G, and contains an example of the use of GCML and CSI. 
This example is needed to do optional exercise 6 for this module. 

Now do the Tests/Exercises for this module in the Tests and 
Exercises book. They are all lab problems. Check your answers 
against the solutions provided, either the on-line files (should 
be under UFD [202,2]) or the printed copies in the Tests/ Exerc ises 
book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be finished with this course. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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APPENDICES 



AP 



APPENDIX A 
SUPPLIED MACROS 



The supplied macros are designed for simple invocation. They 
are intended for use early in the course (before QIOs are taught) 
to provide easy ways of doing I/O fro TI : , and in labs to make 
writing programs easier for the student. They are also used in 
some example programs to allow brevity of code and to establish 
consistency in error checking. 

These macros are contained in the macro library PROG MACS .MLB 
and can be assembled by using the following assembler and 
task-builder calls: 

MACRO/LIST LB: [1,1] PROGMACS/LIBRARY, dev: [uf d] SAMPLE 
(in MCR, MAC SAMPLE, SAMPLE=LB: [1,1] PROGMACS/ML, dev: [ufd] SAMPLE) 

LINK/MAP SAMPLE, LB: [1,1] PROGSUBS/LIBRARY ! Needed to include 

! the internal 
! subroutines 

(in MCR, TKB SAMPLE , SAMPLE=SAMPLE , LB :[ 1 , 1 ] PROGSUBS/LB) 

NOTE 

If you make copies of PROGMACS .MLB and 
PROGSUBS.OLB in your UFD (or enter a 
synonym), then the LB: [1,1] and the dev: [ufd] 
can be omitted. 

This appendix includes directions for using the 
macros, the MACRO-11 source code for the macros, 
internally-called subroutines. 



supplied 
and any 
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SIMPLE MESSAGE OUTPUT 



Invocations : 



Description: 



Examples : 



TYPE 
TYPE 
TYPE 



<message> 
<message>, , psect 
message-address , message-length 



In the first two forms, supply the text of 
the message; the macro will generate the 
storage. Use the second form if you are pro- 
gramming in a Psect other than the default; 
supply the name of the Psect in which you are 
writing . 

In the third form, provide the message address 
and length using standard addressing modes. 
The message can be ASCII or ASCIZ. If it is 
ASCIZ, supply a value of for the message 
length; if it is ASCII, supply the length in 
bytes. 



MSG1: . ASCIZ 
MSG2: .ASCII 
MSG2LN=.-MSG2 



/THIS IS MESSAGE #1/ 
/THIS IS MESSAGE #2/ 



Outputs : 



TYPE #MSG1,#0 

TYPE #MSG2,#MSG2LN 

TYPE <THIS IS MESSAGE #3> 

All registers are preserved. 

C-bit is set for error; 
clear for no error. 



Note : 



Task-Building 



Event flag 24(10) is used for synchronization, 
Avoid using this flag for other purposes in 
your task. 

This macro requires subroutine modules TYPOUT 
and LENGTH from PROGSUBS. OLB . 
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SIMPLE MESSAGE INPUT 



Invocations : 
Description : 

Outputs : 



INPUT 



buffer , length 



Note : 



Task-Building 



Accepts input data from TI:, into specified 
buffer. Length is in bytes. Use standard 
addressing modes for all arguments. 

R0 points to the input buffer. 

Rl contains the byte count from the I/O status 
block if there is no error. 

C-bit is set for error; 
clear for no error. 

For directive errors, Rl is clear; $DSW 
contains directive error code. 

For I/O errors, Rl contains error code 
from the I/O status block. 

Event flag 24(10) is used for synchron- 
ization. Avoid using this flag for other 
purposes in your task. 

This macro requires subroutine module TYPIN 
from PROGSUBS.OLB. 
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ERROR MESSAGE MACROS 



Error message macros generate error messages appropriate to 
Executive directives, I/O operations, and FCS calls. 

• All macros have message, length, and Psect arguments whose 
interpretations are identical to those for the TYPE macro. 
These are used to specify the user-defined section of the 
error message. 

• The calling program must check for acceptable errors 
before calling the error message macro, because the error 
routine aborts the task. 

• All macros exit unconditionally with "severe error" status 
after the error message is printed. 

• All macros require the subroutine modules EREXIT, TYPOUT, 
and LENGTH from PROGSUBS . OLB . 



EXECUTIVE DIRECTIVE ERRORS 



Invocations : 



DIRERR 
DIRERR 
DIRERR 



<message> 
<message>, , psect 
message-address , message- length 



Notes : 



User should check C-bit and dismiss acceptable 
errors before calling DIRERR. 



Format of 
Message : 



DIRECTIVE ERROR 
<user-def ined message> 
DSW = <value>. 
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I/O ERRORS 

Invocations 

Notes : 



Format of 
Message : 



IOERR 
IOERR 
IOERR 



iosb , <message> 

iosb , <message> , ,psect 

iosb , message -add res s , message- length 



iosb is a pointer to the I/O status block. 

User should check the low-order byte of the 
first word of the I/O status block, and dismiss 
acceptable errors before calling IOERR. 

I/O ERROR 

<user-def ined message> 

I/O STATUS BLOCK = <hb> , <lb>/<2nd word> 

hb is the high byte of the first word, 
lb is the low byte of the first word. 



FCS ERRORS 

Invocations 

Notes : 



Format of 
Message : 



FCSERR f db,<message> 

FCSERR f db,<message>, ,psect 

FCSERR fdb, message-address , message-length 

fbd is a pointer to the file descriptor block 
for the operation which caused the error. 

User should check the C-bit and/or check F.ERR 
in the FDB, and dismiss acceptable errors before 
calling FCSERR. 

FCS ERROR 

<user-def ined message> 
DSW = <value> 



or 



FCS ERROR 

<user-def ined message> 
I/O ERROR CODE = <value>. 
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MACRO- 1 1 CODE FOR SUPPLIED MACROS 



1 

3 
4 

5 
6 
7 
8 
9 
10 
.1.1 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 



♦MACRO TYPE 
♦NLIST 



MESSG t LEN y PSCT 



COPYRIGHT. <C> 1981 BY DIGITAL EQUIPMENT CORPORATION 
Macro to invoke the "TYPOUT" routine to type a line on 

ti: ♦ 

Invoke using one of two forms* 
TYPE <message> 
TYPE address y length 



or 



In the first form you specify the text of the message* 
The macro reserves storage for the string* 

WARNING* The character is used as the delimiter in a 
♦ASCII directive when you invoke the first form? so 
you may not use this character in your message* 

In the second form you must use addressing modes to 
specify the address and length of a string which you 
have reserved in your program* The first argument is 
the address of an ASCII or ASCIZ string* The second 
argument should have a value of if the string is 
ASCIZ? else should be the length of the ASCII string* 
addressing modes using the stack pointer are not 
allowed* 

If you use the first form and are programming in other 
than the blank Psecty you must explicitly provide a 
null "LEN" argument? and specify a third argument 
(psect)* This argument must be the name of the Psect 
in which you are programming* 

Needed subroutine modules* TYPOUT and LENGTH 



symbols SAV*Rn 



♦ LIST 

♦ GL0BL TYPOUT 
SAV*R0 * ~1 
SAv\Rl = -1 
SAv\R2 = -1 



-1 if Rn is not saved on the 
stack 

indicates Rn is stored on 
the stack at SAv"*Rn<SP> ♦ 



5 Subroutine to issue QI0 
r directive 

y Assume no need to save 
? R0 

f Assume no need to save 
y Rl 

9 Assume no need to save 
? R2 
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54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 
102 
103 



♦ IF B 



LEN 

♦PSECT MSGTXT 

**$MES=» 

♦ASCII X MESSG X 

$**LEN~*~-***MES 

♦PSECT PSCT 



MOV 
MOV 
MOV 
MOV 

SAV.RO 
SAV»R1 



ROy~<SP> 
#$*$MESyRO 
Rly-(SP) 
*$*$LENyRl 

•■ 



♦ IFF 



Blank LEN arg means 

first form 
Set up text in Psect 

MSGTXT 



Back to original Psect 

Save old RO 

RO ~> message 

Save old Rl 

Rl - message length 

Note RO saved on stack 

Note Rl saved on stack 



Second form of 
invocation 

9 If arguments are not already in the correct registers* 
y save them temporarily on the stack 



♦ NTYPE ADM ♦ Al yMESSG 



♦ IF 
MOV 

SAV*R0 

SAV»R2 

♦ ENDC 



NEy ADM+ Al 
MESSGy-(SP) 

" 

- 



y Addressing mode of 

r MESSG 

y If anything but "RO" 

i Save argument on the 

r stack 

? RO will be saved here 

? later 

y We'll need to save R2 



♦ NTYPE ADM + A2y LEN 

♦IF NEyADM»A2-l 

MOV LENy-(SP) 

SAV*R1 







y Addressing mode of LEN 
y If anything but "Rl" 
y Save argument on the 
y stack 

y Rl will be saved here 
y later 

♦I IF GEySAV»ROy SAV*R0=SAV,R0+2 y Increase 

f offset of RO 
SAV*R2 =0 ? We'll need to save R2 

♦ ENDC 

y Swap the registers with their argument values which we 
y stored on the stacks 

♦IF EQySAV*R2 y If we need to save R2 

MOV R2y-(SP> t Save R2 

♦I IF GEySAV*ROy SAV ♦ R0=SAV ♦ RO+2 5 Increase 

y offset of RO 
♦IIF GEySAV*Rly SAV»Rl=SAV*Rl+2 5 Increase 

y offset of Rl 

♦ ENDC 
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104 




♦ IF 


GEvSAV»RO 


i 


If RO's ar<3 W3s put on 


105 








t 


stack r 


106 




MOV 


R0yR2 


5 


swap RO with its 


107 




MOV 


SAV^RO(SP) *R0 


? 


argument value 


108 




MOV 


R2?SAV t R0(SP) 






109 




♦ ENDC 








110 












111 




♦ IF 


GE?SAV,R1 


9 


If Rl's ar£ U3S put on 


112 








i 


stack 9 


1 1.5 




MOV 


Rl *R2 


9 


Swap Rl with its 


1.14 




MOV 


SAV^RKSP) yRl 


? 


argument value 


115 




MOV 


R2>SAV»RKSP> 






116 




♦ ENDC 








117 












118 


♦ ENDC 






9 


Forms of invocation 


119 












120 




CALL 


TYPOUT 






121 


r Restore registers 






122 




♦I IF GE 


>SAV»R2v MOV 


<SP)+yR2 f Restore old R2 


123 




♦I IF GE 


ySAV*Rl> MOV 


(SP)+rRl 9 Restore old Rl 


124 




♦I IF GE 


,SAV,RO, MOV 


< 


SP)+yR0 9 Restore old RO 


125 




♦ ENDM 


TYPE 
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1 

2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
.1.2 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 



♦ MACRO INPUT BUFFER ?LEN 

? 

? COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

9 

9 Macro to invoke the "TYPIN" routine to input data from 

ti: ♦ 

Invoke us ins* 

INPUT address? length 

where address and length are the address and 
length of the input buffer* 



outputs: 



Dat3 is input synchronously from LUN 5 
R0 -> buffer 

C-bit is set for error? clear for no 
error (for directive or I/O errors) 

If no error? Rl contains byte count from 
I/O status block* 

If a directive error is encountered? Rl 
is clear? $DSW contains error code 

If an I/O error is encountered? Rl 
contains error code from I/O status block 



Needed subroutine module* TYPIN 
WARNINGS* 



♦ IF 

♦ ENDC 

♦ IF 

♦ ENDC 



!♦ ROUTINE USES EVENT FLAG #24 FOR 
SYNCHRONIZATION 
2. R0 AND Rl ARE DESTROYED 



♦GLOBL TYPIN ? Subroutine to issue (HQ 
? directive 

♦NTYPE ADRMOD? BUFFER ? Check addressing mode 
NE?ADRM0D ? Eiuffer pointer already in R0? 

MOV BUFFER ?R0 ? No? move it there 

♦NTYPE ADRMOD ?LEN ? Check addressing mode 
NE?ADRM0D--1 ? Length already in Rl? 

MOV LEN?R1 9 No? move it there 



CALL 
♦ ENDM 



TYPIN i Call subroutine to issue QIO 
? directive 
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TITLE TYPOUT Subroutine to output to Tit 



6 
7 
8 
9 
.1.0 
.1. :l. 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
i>9 

30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 



y COPYRIGHT <C> 1981 BY DIGITAL EQUIPMENT CORPORATION 
y 

? TYPOUT provides a simple way for MACRO-11 routines to 

5 type out a message on Ti:* 



y CALL J 
y 

9 inputs: 



y outputs: 



warning: 



JSR PC y TYPOUT 

RO =•"> ASCII or ASCIZ message 
Rl ~ if string is ASCIZ 

» n>0 for ASCII string of length n 

LUN 5 is assumed to be assigned to TI* 

Message is output synchronously to LUN 5 

All registers preserved 

C-bit is set for error y clear for no 
error 

Routine uses event flag #24 for 
synch ran i zat ion 



y The macro "TYPE" can be used to invoke this routine 
? in a fairly transparent manner* 



♦ GLOBL LENGTH 
♦MCALL QI0W*S 



typout:: TST 

BNE 



i*: 



CALL 

MOV 
SUB 
MOV 



Rl 
1$ 

LENGTH 

R2 y - ( SP ) 

#4ySP 

SPyR2 



Subroutine to determine 

length of string 
System macro 

ASCII input or ASCIZ? 
Branch if ASCII* Rl 
already has length 
Find length of string 

(returned in Rl ) 
Save R2 on stack 
Reserve space for I0SB 
5 R2OI0SB 



y Do a garden variety output to TI* 

QI0W*S #10 ♦ WMB y #5 y #24 ♦ y y R2 y y <R0 y Rl y #40> 

BCC 2$ y Branch on directive OK 



ADD 



#4 y SP 



y Directive error* Purge 
y I0SB from stack 
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47 BR 6* 5 Exit (with Obit set) 

48 ? 

49 5 Directive? succeeded* Record any I/O errors? record 

50 r byte count? purge stack 

51 i 

52 2*: CMPB *rS«SUC*<SP)+ 9 I/O error? 

5.3 BEG 4$ ? Branch if no error 

54 3$ J SEC v Set C~bit to indicate 

55 i error 

56 BR 5$ 9 Branch to get I/O count 

57 4* J CLC v Clear C-~bit to indicate 

58 i no error 

59 5*i TST <SP> + 9 Clean up stack 

60 9 

61 J COMMON EXIT 

62 r 

63 6* J MOM (SP)+fR2 ? Restore R2 

64 RETURN J Return 

65 ♦ END 
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3 
4 
5 
6 
7 
8 
9 
10 
1 1 
12 
1 3 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 



♦TITLE TYPIN Subroutine to input from TIJ 

9 

9 COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

9 

9 TYPIN provides a simple way for MACRQ-11 routines to 
9 input data from TI** 



y CALL. * 

9 

9 INPUTS? 

9 
9 
9 
9 

9 OUTPUTS ♦ 



WARNING X 



JSR PC 9 TYPIN 

RO ~> Input buffer 

Rl ~ Length of buffer in bytes 

LUN 5 is assumed to be assigned to TI* 

Data is input synchronously from LUN 5 

R is u n c h a n s e d 

C-bit is set for error? clear for no 
error (for directive or 1/0 errors) 

If no error? Rl contains byte count from 
1/0 status block* 

If a directive error is encountered? Rl 
is clear? $DSW contains error code 

If an 1/0 error is encountered? Rl 
contains error code from 1/0 status 
block 

ROUTINE USES EVENT FLAG #24 FOR 
SYNCHRONIZATION 



The macro "INPUT" can be used to invoke this routine 
i n a f a i r 1 y t rsnspsre n t m a n n e r ♦ 



♦ MCALL QI0W*S 



9 System macro 



TYPIN * * MOV R2?--(SP) ? Save R2 

SUB #4?SP ? Reserve space for I0SB 

MOV SP?R2 ? R2=OI0SB 

? Do a harden variety input from TI* 

Q 1 0W*S # 1 ♦ RVB ? #5 ? #24 ♦ ? ? R2 ? ? <R0 ? R 1 > 



BCC 
ADD 

CLR 
SEC 
BR 



#4?SP 



Rl 



6* 



? Branch on directive OK 

? Directive error* Purae 

? I0SB from stack 

? Note directive error 

? 

? exit 
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53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 



v Directive succeeded* Check 
? byte count? purge stack 



2*: 



4$: 



MOV 
CMPB 
BEQ 
TST 

SEC 



BR 

CLC 
MOV 



COMMON EXIT 



6$J 



MOV 

RETURN 
♦ END 



<SP)+?R1 

#IS*SUC?R1 

4$ 

< SP ) + 



<SP)+ ?R1 



<SP)+»R2 



for I/O errors? record 



Get success/error code 
I/O error? 
Brnch if no error 
Error* Forget about 

I/O count 
Just return with C-bit 
set and I/O status in 
Rl 

Branch to common exit 
Clear carr^ bit 
y Return I/O count in Rl 



Restore R2 
Return 



3 
4 
5 
6 
7 
8 
9 
10 
11 



♦TITLE LENGTH 
COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 
LENGTH finds the length of an ASCIZ string 



call: 

input: 

output: 



12 


9 




Rl = 


13 


9 






14 


r 






15 


length: 


* CLR 


Rl 


16 




MOV 


R0»-<SP> 


17 








18 


i*: 


TSTB 


<R0) + 


19 








20 




BEQ 


2$ 


21 








22 




INC 


Rl 


23 




BR 


1$ 


24 


2*: 


MOV 


<SP)+?R0 


25 








26 




RETURN 




27 




♦ END 





CALL LENGTH 

RO => ASCIZ string 

RO preserved 

Length of string (not including 
term i nat i ng nu 11) 



Clear counter 
S3ve pointer to 

beginning of string 
Real character or null 

byte? 
Null means end of 

string 
Count real character 
And look at next byte 
Restore original 

pointer 
Return 
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1 . MACRO DIRERR MESSAGyLENy PSCT 

2 f 

3 J COPYRIGHT <C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

4 ? 

5 y Macro to generate a "directive error" message and 

6 y print out the value of the DSWy plus a user-defined 

7 y message* The task is forced to exit after the message 

8 f is printed* 

9 5 

10 y The form of the resultant error message is* 
115 

12 y DIRECTIVE ERROR 

13 y <USER-~DEFINED MESSAGED- 

14 y DSW = <VALUE> 

15 y 

16 P It is suggested that the user-defined message identify 

17 y the operation which returned the error* 

18 y 

19 y It is the caller's responsibility to check the c~bit 

20 y prior to invoking DIRERR* This convention allows the 

21 y user to accept certain types of errorsy then invoke 

22 y DIRERR for any other kinds of errors* 

23 y 

24 y Invoke using one of two forms* 

25 y 

26 y DIRERR <message> 

27 ? or 

28 y DIRERR ADDRESS t LENGTH 

29 y 

30 y In the first form you specify the text of the message* 

31 y The macro reserves storage for the string* 

32 5 

33 y In the second form you must use addressing modes to 

34 y specify the address and length of a string which you 

35 5 have reserved in your program* The first argument is 

36 J the address of an ASCII or ASCIZ string* The second 

37 y argument should have a value of if the string is 

38 y ASCIZ y else should be the length of the ASCII string* 

39 9 

40 y If you use the first form and are programming in other 

41 y than the blank Psecty you must explicitly provide a 

42 y null "len" argument* and supply as the third argument 

43 y the name of the Psect to return to* 

44 y 
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45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
5? 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 



♦GLOBL EREXIT 
♦GLOBL DIRER I 



♦ GLOBL ERARGS - 

y Offsets into argument block* 

♦ GLOBL E.RUMA 

♦GLOBL E ♦ RUML 



♦ IF B 



***ME* 



♦GLOBL 

MOV 
LEN 



E.RDSW 

♦ERARGSy R2 



Common routine 
"DIRECTIVE ERROR" 

input string for 

*EDMSG 
$EDMSG argument block 

User-message address 
User-message length 
DSW V3lue 

R2=>*EDMSG arg block 
Blank len arg means 
first form 



♦PSECT MSGTXT 



♦ASCII /MESSAG/ 
***LEN=*--*$$MES 

♦PSECT PSCT 
MOV 



♦ IFF 



♦ ENDC 



MOV 



MOV 
MOV 



MOV 
MOV 
JMP 

♦ ENDM 



#$$*MESyE*RUMA<R2 
*$$$LEN r E ♦ RUML < R2 



MESSAG y E ♦ RUMA < R2 ) 
LEN y E ♦ RUML < R2 ) 



*DSUI»E*RDSU(R2) i 
♦DIRERI yR3 r 
EREXIT i 



) f Load message addr 
) r and message length 
5 into arg block 

? Load message addr 
y and message length 
y into arg block 

Load DSW into 3rg block 
R3->*EDMSG input string 
Jump to common error 
exit routine 
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♦MACRO IOERR 



IOSB*MESSG>LENyPSCT 



r + 



3 
4 
5 
6 
7 
8 
9 
10 
11 
1 *•* 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 

an 



COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

Macro to Generate 3n "I/O error" message and print out 
the value of the I/O status block* plus a user-defined 
message* The task is forced to exit after the message 
is printed* 

The form of the resultant error message is* 
1/0 ERROR 

< user-defined message > 

1/0 STATUS BLOCK = <hh> r <lb>/<2nd word> 

where? "hb" and "lb" are the high byte and low byte of 
the first word of the I/O status block* 

It is suggested that the user-defined message identify 
the operation which returned the error* 

It is the caller's responsibility to check the first 
word of the 1/0 status block prior to invoking IOERR? 
to see whether the operation has been a success or a 
failure* This convention allows the user to accept 
certain types of errors? then invoke IOERR for any 
other kinds of errors* 

Invoke using one of two forms* 

1 ERR i o s b » < message > 

IOERR iosb y address r length 



or 



In either form "iosb" is the address of the 1/0 status 
block r in any addressing mode* 

In the first form you specify the text of the message* 
The macro reserves storage for the string* 

In the second form you must use addressing modes to 
specify the address and length of a string which you 
have reserved in your program* The second argument is 
the address of an ASCII or ASCIZ string* The third 
argument should have a value of if the string is 
ASCIZ * else should be the length of the ASCII string* 

If you use the first form and are programming in other 
than the blank Psect? you must explicitly provide a 
null "LEN" argument? and supply as the fourth argument 
the name of the Psect to return to* 
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53 ♦GLOBL EREXIT r Common routine 

54 .GLOBL IOERIN y "I/O ERROR" input 

55 y string for *EDMSG 

56 ♦ GLOBL ERARGS J *EI«MSG argument block 

57 5 Offsets into argument block* 

58 ♦ GLOBL E»RUMA y User-message address 

59 ♦GLOBL E*RUML y User-message length 

60 ♦ GLOBL E*RIOS ? First word of I/O 

61 r status block 

62 y 

63 MOV #ERARGS t R2 i R2=>*EDMSG arg block 

64 ♦ IF B LEN 5 Blank LEN arg means 

65 ? first form 

66 ♦PSECT MSGTXT 

67 $**MES==* 

68 ♦ASCII /MESSG/ 

69 ,*$$LEN=*"*$$MES 

70 ♦ PSECT PSCT 

71 MOV #$$*MES*E*RUMA<R2> y Load message sddr 

72 MOV #$$$LEN y E ♦ RUML ( R2 ) y and message length 

73 r into arg block 

74 *IFF 

75 MOV MESSG y E ♦ RUM A ( R2 ) y Load message addr 

76 MOV LENyE*RUML(R2) y and message length 

77 y y into arg block 

78 vENDC 

79 y Copy I/O status block into $EDMSG arg block 

80 MOV lOSByRl y Rl => I/O status block 

81 MOVB KRl)yR3 y Get hi bate of first 

82 ? y word (and sign-extend 

83 y J it) 

84 MOV R3yE*RI0S(R2) y Copy into arg block 

85 MOVB (R.l)yR3 y Get lo byte and 

86 y sign-extend 

87 MOV R3yE*RI0S+2(R2) J Copy into arg block 

88 MOV 2(R1 ) yE»RI0S+4(R2) y Copy 2nd word of 

89 y I0SB 

90 MOV #I0ERINyR3 ? R3 ~> *EDMSG input 

91 y string 

92 JMP EREXIT y Jump to common error 

93 y exit routine 

94 ♦ ENDM 
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4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 

24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 



♦ MACRO FCSERR FDB y MESSG y LEN r PSCT 

COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

Macro to generate an "PCS ERROR" messasie and print out 
the error code plus 3 user-defined message* The task 
is farced to exit 3fter the message is printed* 

The form of the resultant error message is* 

FCS ERROR 

<USER~DEFINED MESSAGE.:- 
DSW <VALUE> 

or 

FCS ERROR 

<USER~DEFINED MESSAGE!--- 
I/O ERROR CODE « <VALUE> 

It is suggested that the user-defined message identify 
the operation which returned the error* 

It is the caller's responsibility to check F*ERR in 
the FDB prior to invoking FCSERR r to see whether the 
operation has been a success or a failure* This 
convention allows the user to accept certain types of 
errors* then invoke FCSERR for any other kinds of 
errors* 

Invoke using one of two forms* 



or 



FCSERR f db t <message> 
FCSERR fdb» address? length 



In either formr "fdb" is the address of the file 
descriptor block for the FCS operation which has 
generated the error* 

In the first form you specify the text of the message* 
The macro reserves storage for the string* 

In the second form you must use addressing modes to 
specify the address and length of a string which you 
have reserved in your program* The second argument is 
the address of an ASCII or ASCIZ string* The third 
argument should have a value of if the string is 
ASCIZ* else should be the length of the ASCII string* 

If you use the first form and are programming in other 
than the blank Psect* you must explicitly provide a 
null "len" argument? and supply as the fourth argument 
the ri3me of the Psect to return to* 
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56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 



♦ GLOBL. EREXIT 

♦GLOBL FCSDIR>FCSIO 

♦GLOBL ERARGS 

f Offsets into argument block* 

♦GLOBL E^RUMA 

♦ GLOBL E*RUML 

♦GLOBL E^RCQD 



♦MCALL FDOF*L 
FDOF$L 



♦ IF B 



***MES= 



MOV 
LEN 



♦ERARGS >R2 



Common routine 
$EDMSG input strings 
$EDMSG 3 r gumen t block 

User-mess3ge address 
User-messsge length 
Error code (DSW vslue 
or I/O error) 



f Define FDB offsets 

i R2=>$EDMSG arg block 

i Blank len arg means 

i first form 



♦PSECT MSGTXT 



♦ASCII /MESSG/ 
***LEN=»-*$*MES 

♦PSECT PSCT 

MOV #$**MES,E*RUMA<R2 
#*$*LEN*E«RUML(R2 



♦ IFF 



♦ ENDC 



MOV 



MOV 
MOV 



MOV 

MOVB 

MOV 
TSTB 



MESSG y E ♦ RUMA < R2 ) 
LEN»E*RUML(R2) 



FDB? Rl 

F.ERR(Ri) >R0 

R0*E»RC0D(R2) 
F.ERR+KR1) 



BEQ 10 
f Directive error* 

MOV #FCSDIR>R3 



io: 



JMP 
MOV 
JMP 
♦ ENDM 



EREXIT 

#FCSI0>R3 

EREXIT 



) r Load message addr 
) r and message length 
J into arg block 

r Load message addr 
? and message length 
r into arg block 

Rl~> file descriptor 

block 
Get error code 

(sign-extend) and 

store into 3rg block- 
Directive error or I/O 

error? 
Branch on I/O error 

R3=> "FCS DIRECTIVE 
ERROR" $EDMSG string 
Jump to common error 

exit routine 
R3=>"FCS I/O ERROR" 
$EDMSG string 
Jump to common error 

exit routine 
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4 
5 
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7 
8 
9 
10 
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12 
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14 
15 
16 
17 
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28 
29 
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32 
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♦TITLE EREXIT ERROR EXIT ROUTINE 

COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 

This is a common exit routine C3lled by the 
error-processing macros DIRERR* 1'OERRy and FCSERR* It 
types out an error message 3nd forces the task to exit 
with status "severe error"* 



Call : 
Inputs * 



JMP 

R2 



R3 «> 

♦ GLOBL $EDMSG 

♦ GLOBL LENGTH 

♦ MCALL EXST*C 

♦ MCALL TYPE 

? 

EX*SEV « 4 

J 

v $EDMSG input strings* 



DIRER I * * ♦ ASCII /INDIRECT I'VE ERROR/ 
♦ASCII /%N%VA/ 
♦ASCIZ /%NDSW « ZD/ 



fcsdir:: ♦ascii /%nfcs error/ 
♦ asci i /znzva/ 
♦asciz /%ndsw =» zd/ 



ioerinj: ♦ASCII 0ZNI/O error© 

♦ASCII /ZNZVA/ 

♦ ASCIZ ©ZNI/O STATUS BLOCK 

r 

fcsio:: ♦ascii @znfcs error© 

♦ ascii /znzva/ 

♦asciz ©zni/o error code = 

5 

9 



EREXIT 

ERARGS ( $EDMSG argument block? 

defined in this routine) 

The argument block has alresdy 
been filled in with the 
user-message descriptor* and the 
system error code (DSW value or 
I0SB pointer) ♦ A user-message 
length = means that the 
user messsge is in ASCIZ form^ 

One of the *EDMSG input strings 
defined in this routine 



i Computes length of 

i ASCIZ string 

r System macro 

t Supplied macro 

? Error exit status 



ZD* ZD / ZD@ 



ZD@ 
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54 
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64 
65 
66 
67 
68 
69 
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80 
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84 
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86 
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outbuf: .blkb 200 ♦ 

♦ EVEN 

? $EDMSG argument block 
ERARGS : : 

E ♦ RUML== ♦ -ERARGS 

♦ WORD 

E ♦ RUMA=~ ♦ -ERARGS 

♦ WORD 
.» Error codes 

E ♦ RDSW-- ♦ -ERARGS 
E»RI0S~~* -ERARGS 
E ♦ RC0D~= ♦ -ERARGS 

♦ WORD 

♦ WORD 

♦ WORD 



EREXIT ♦ ♦ 



y 



TST E ♦ RUML (R2) 

BNE 1$ 

MOV E»RUMA(R2) yRO 

CALL LENGTH 

MOV R1>E*RUML(R2> 

MOV *OUTBUF*RO 

MOV R3*R.l 



CALL *EDMSG 

TYPE #0UTBUF>R1 

EXSTSC EX$SEV 
♦ END 



? $EDMSG output buffer 

? User-message length 

r User-message address 

t DSW for DIRERR 

5 I0SB for I0ERR 

t PCS code for FCSERR 



User message ASCII or 

ASCIZ? 
ASCII 

If ASCIZ? find length 
RO ~> user message 
(returned in Rl) 
Set length field in 

argument block 
Output buffer for 

$EDMSG 
Put input string 

pointer into proper 

register for $EDMSG 
(returns length in Rl) 
Type out formatted 

message 
Exit/severe error 
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APPENDIX B 
CONVERSION TABLES 



Table B-l Decimal/Octal, Word/Byte/Block Conversions 
Words (10) /Words (8) Bytes (10) /Bytes (8) Blocks (1 0) /Blocks (8 ) 





1/1 


2/2 






32/40 


64/100 


1/1 


IK 


=1024/2000 


2048/4000 


32/40 


2K 


=2048/4000 


4096/10000 


64/100 


4K 


=4096/10000 


8192/20000 


128/200 


8K 


=8192/20000 


16384/40000 


256/400 


16K 


=16384/40000 


32768/100000 


512/1000 


32K 


=32768/100000 


65536/200000 


1024/2000 


64K 


=65536/200000 


131072/400000 


2048/4000 


128K= 


= 131072/400000 


262144/1000000 


4096/10000 



Table B-2 APR/Virtual Addresses/Words Conversions 



APR 


Virtual Addresses 


Words 





000000-017776 


0-4K 


1 


020000-037776 


4-8K 


2 


040000-057776 


8-12k 


3 


060000-077776 


12-16K 


4 


100000-117776 


16-20K 


5 


120000-137776 


20-24K 


6 


140000-157776 


24-28K 


7 


160000-177776 


28-32K 
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APPENDIX C 
FORTRAN/MACRO- 11 INTERFACE 

CALLING A MACRO- 1 1 SUBROUTINE FROM A FORTRAN PROGRAM 

FORTRAN Program Call: 

CALL SUBNAM (I,J,K) 
MACRO translation: 

1. Set up table of arguments. 





Count 


= 3 


Address of 


I 


Address of 


J 


Address of 


K 



2. Issue subroutine call. 

JSR PC, SUBNAM 
or 

CALL SUBNAM 
The FORTRAN Callable MACRO-11 Subroutine 
; Accessing: 

; Argument count = (R5) 

Argl = @2(R5) 
Arg2 = @4(R5) 
Arg3 = @6(R5) 

SUBNAM:: 

RTS PC ; or RETURN 
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CALLING A FORTRAN PROGRAM FROM A MACRO- 1 1 PROGRAM 



In the MACRO program: 



LINK: 



.BYTE 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



3, 



A: 
B: 
C: 



A 
B 
C 
2 
3 




MOV 
JSR 



#LINK,R5 
PC, SUB 



In the FORTRAN program: 

SUBROUTINE SUB (L,M,N) 

N=L+M 

RETURN 

END 

NOTE 

This method is also used to call a FORTRAN 
callable subroutine (written in MACRO-11). 

Example 7-3 in the Static Regions module shows a shareable 

library LIB .MAC , which contains FORTRAN callable subroutines. 

USELIB.MAC, also in Example 7-3, shows a referencing task which 
calls subroutines in the library. 
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APPENDIX D 
PRIVILEGED TASKS 



RSX-11M systems have two classes of tasks, privileged and 
nonpr i vileged . The basic difference is that privileged tasks have 
certain system-access capabilities that nonpr ivi leged tasks do not 
have. These privileges include one or more of the following: 

• Access to Executive routines and data structures 

• Automatic mapping to the I/O page 

• Bypass of system security features. 

NOTE 

Privileged tasks may be hazardous to a run- 
ning system. 

Use one of the following qualifiers (switches) to build a 
privileged task. 

1. /PRIVILEGED qualifier (MCR /PR:0) 

This task is built in the same way as a nonpr ivi leged task 
and does not map to the Executive or the I/O page. It 
can, however, do the following: 

• Bypass file protection 

• Issue directives which require privileges (e.g., Alter 
Priority, QIO for Write Logical Break-through) 

• Issue QIOs to write logical blocks to a mounted 
volume, regardless of who issued the MOUNT or ALLOCATE 
command . 

2. /PRIVILEGED or /PRIVILEGED (MCR /PR:4 or /PR:5) 

This task has the privileges of a /PRIVILEGE : task, plus 
it maps to the Executive and the I/O page. The user task 
code is mapped beginning at APR 4 or 5, as specified. The 
APRs below the one specified are used to map to the 
Executive, and APR 7 is used to map the I/O page. Use 
/PRIVILEGE : 4 if the Executive is 16K words or less; use 
/PRIVILEGE : 5 if the Executive is between 16K and 20K 
words. If the task code extends beyond the end of the 
addresses mapped by APR 6, then APR 7 is used to map the 
excess code, and the task does not map to the I/O page. 
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Privileged tasks are discussed in detail in the RSX-11M 
Internals Course. See also Chapter 6 on Privileged Tasks in the 
RSX-11M/M-PLUS Task Builder Manual. 
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APPENDIX E 

TASK BUILDER USE OF PSECT ATTRIBUTES 

The Task Builder collects scattered occurrences of program 
sections of the same name and combines them in a single area in 
your task image. The program section attributes control how the 
Task Builder collects and places each program section. 

See Chapter 2 of the RSX-11M/M-PLUS Task Builder Manual for a 
complete discussion of program section attributes. 

Example of allocation code attributes: 
CON (concatenate) versus OVR (overlay) 

1. A. OBJ has Psect Q,CON - length 100(10) words 
B.OBJ has Psect Q,CON - length 50(10) words 
When task-built: 

LINK A,B 

Yields 150(10) words in Psect Q 

(first A's 100(10) words, then B's 50(10) words). 

2. A. OBJ has Psect Q,OVR - length 100(10) words 
B.OBJ has Psect Q,OVR - length 50(10) words 
When task-built: 

LINK A ,B 

Yields 100(10) words in Psect Q 

(A's 100(10) words. B's 50(10) words are the 

same as A's first 50(10) words). 
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Example of scope code attributes: 

LCL (local) versus GBL (global) 

Overlay Tree B.ODL file: 

B3 
I 

Bl B2 .ROOT B-*! (B1,B2-B3) 

I I . END 

^ 

B 

Task-build command (for all): LINK B/OVERLAY DESCRIPTION 

1. B. OBJ has Psect Q, LCL, CON - length 100(10) words 
B1.0BJ has Psect Q, LCL , CON - length 50(10) words 
When task-built: 

Yields 100(10) words in Psect Q in root segment B 
Yields 50(10) words in Psect Q in overlay segment Bl 

2. B.OBJ has Psect Q, GBL, CON - length 100(10) words 
B1.0BJ has Psect Q, GBL, CON - length 50(10) words 
When task-built: 

yields 150(10) words in Psect Q in root segment B (in the 
segment closest to the root); B's 100(10) words, then 
Bl's 50(10) words. 

If GBL, OVR instead, yields 100(10) words in Psect Q in the 
root segment. B's 100 words, with Bl's 50(10) words the 
same as B's first 50(10) words. 
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3. B2.0BJ has Psect Q (LCL or GBL) - length 100(10) words 
B3.0BJ has Psect Q (LCL or GBL) - length 50(10) words 
When task-built: 

If CON, yields 150(10) words in Psect Q in overlay segment 
B2 (allocation collected, since it is all in the same 
overlay segment) . 

If OVR instead, 100(10) words in Psect Q in overlay 
segment B2. B3*s 50(10) words are the same as B2's first 
50(10) words. 

LCL and GBL are used only for overlaid tasks. In a 
non-overlaid task or within an overlay segment in an overlaid 
task, allocations are collected when either LCL or GBL is 
specified, as in Example 3. 

Example of FORTRAN COMMONS at Psects : 

Psect attributes are always: RW, D,GBL, OVR, RE L 

COMMON /RDATA/ 1(100) 
Macro translation: 

.PSECT RDATA, RW, D, GBL, OVR, REL 
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APPENDIX F 

ADDITIONAL SHARED REGION TOPICS 



SHARED REGIONS WITH OVERLAYS 

• Can be referenced using a smaller window in referencing 
task 

• Reuse virtual addresses in the referencing task 

• Must be memory-resident overlays 

• Have overlay structures which are placed in the .STB file 
and later placed in root segment of referencing task. 



BUILDING A RESIDENT LIBRARY WITH OVERLAYS 

1. Code and assemble library modules. 

2. Write regular .ODL file to define overlay structure. 

• Typical structure has a null root. 

3. Task-build as a shared region. 

• Only symbols defined or referenced in the root are 
included in the .STB file. 

• Force inclusion of global references into root, when 
necessary, using GLBREF option. 

Example .ODL file OVRLIB.ODL (Figure F-l) : 

.NAME OVRLIB 

.ROOT OVRLIB-*! (H, I-J) 

.END 



Example task-build command: 

>LINK/NOHEADER/MAP/SYMBOL_T ABLE/OPT IONS OVRLIB/OVERLAY- 

->_DESCRIPTION 

Option? STACK=0 

Option? PAR=OVRLIB: 140000: 40000 
Option? GBLREF=H , I , J 
Option? <RET> 
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Referencing task is created using regular procedure to 
reference library OVRLIB. 

See section 5.1.4 (on Shared Regions with Memory-Resident 
Overlays) in the RSX-11M/M PLUS Task Builder Manual for additional 
information . 

PHYSICAL 
MEMORY 



VIRTUAL 
MEMORY 



160000 APR 7 
140000 APR6 
120000 APR 5 
100000 APR 4 



60000 APR 3 - 



40000 APR 2 
20000 APR 1 

APR0 




Figure F-1 A Shared Region With Memory-Resident Overlays 
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REFERENCING MULTIPLE REGIONS IN A TASK 

• Use the usual procedure if: 

The number of available APRs in the referencing task 
is sufficient 

Shared regions are logically independent (one library 
does not call the other library) 

• If shared regions are built absolute, APRs (and virtual 
addresses) cannot overlap. 

Example task-build for logically independent libraries (Figure 
F-2) : 

Libraries: ARES built absolute at V.A. 160000(8); length 4K 

words 

BRES built absolute at V.A. 120000(8); length 6K 
words 

Referencing task: REF 

>L INK/MAP/OPTIONS REF 
Option? RESLIB=ARES/RO 
Option? RESLIB=BRES/RO 
Option? <RET> 
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PHYSICAL 
MEMORY 



160000 APR 7 
140000 APR6 
120000 APR 5 
100000 APR4 

60000 APR3 
40000 APR 2 



20000 APR1 _ 



VIRTUAL 
MEMORY 



APRO 




BRES 



ARES 



REF 



Figure F-2 Referencing Two Resident Libraries 
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INTERLIBRARY CALLS 

One library can call another library 

FORRES calls FCSRES 

To build libraries with interlibrary calls, use any of these 
techniques. 

• Build as a single combined library, then build referencing 
task (Figure F-3) . 

• If referenced library does not contain overlays (Figure 
F-4): 

- Build referenced library. 

Build referencing library, specifying referenced 
library to resolve calls. 

Build referencing task, specifying only referencing 
library. 

• If referenced library has overlays (Figures F-5 and F-6) : 

You must revector interlibrary calls to allow access 
to overlay structure and autoload vectors (always in 
root of referencing task) . 

Once revectoring is included, build shared regions and 
referencing task as if regions are logically 
independent . 

Example task-build commands for each technique follow. 
Example task-build command for combined libraries (Figure 

F-3) : 

>LINK/MAP/NOHEADER/SHAREABLE : LIBRARY/S YMBOL_TABLE- 
->/OPTIONS F4PRES , LB : [1,1] F4P0TS/LIBRARY 
Option? STACK=0 

Option? PAR=F4PRES: 120000: 60000 
Option? <RET> 



Referencing task is created using normal procedure to 
reference the library F4PRES. 
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160000 APR 7 
140000 APR6 
120000 APR 5 
100000 APR 4 
60000 APR 3 
40000 APR 2 

20000 APR1 
APRO 



VIRTUAL 
MEMORY 



F4PRES 
(FCSRES) 

12K WORDS 




USER 

(12K WORDS) 



PHYSICAL 
MEMORY 



F4PRES 
(FCSRES) 



USER 



Figure F-3 Referencing Combined Libraries 
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Example task-build commands for building one library, then 
building the second (referencing) library (Figure F-4) : 

>LINK/MAP/NOHEADER/SHAREABLE : LIBRARY/SYMBOL_TABLE- 

->/OPTIONS/CODE:PIC FCSRES 

Option? STACK=0 

Option? PAR=FCSRES: 0: 20000 

Option? <RET> 

>L INK/MAP/NOHEADER/SHAREAB LE : LIBRARY/SYMBOL_TABLE- 

->/OPTIONS F4PRES f LB : [1,1 ] F4POTS/LIBRARY 

Option? STACK=0 

Option? LIBR=FCSRES:RO 

Option? PAR=F4PRES:140000:40000 

Option? <RET> 



Referencing task is created using normal procedure to 
reference just the library F4PRES. F4PRES must be mapped using 
APRs 6 and 7 because it is built absolute. FCSRES is mapped at 
the next available APR, namely APR 5, because it is built position 
independent . 
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160000 APR 7 

140000 APR 6 

120000 APR 5 

100000 APR 4 

60000 APR 3 

40000 APR 2 

20000 APR 1 

APR 



VIRTUAL 
MEMORY 
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(8K WORDS) 



FCSRES 

(4K WORDS) 



USER 
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FCSRES 



USER 



Figure F-4 Building One Library, Then Building 
a Referencing Library 
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FCS1 



FCS2 




F4PCLS 



CALL .OPEN- 



OPEN: 



DISPAT: 



USER 



.FSRPT: 



JMPTBL: 



.OPEN' 

.PUT 

.GET 



AUTOLOAD ROUTINE, MAPS TO 
FGS1, THEN TRANSFERS CONTROL 



Figure F-5 Revectoring 



See Section 5.2.1.3 (on User Task Vectors Indirectly Resolve 
all Interlibrary References) in the RSX-11M/M-PLUS Task 
Builder Manual for additional information on revectoring. See 
also Section 5.2.3 on Examples for commented task-build commands 
for building libraries with revectoring. 
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Example task-build commands when revectoring are used 
(Figure F-6) : 



>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL_TABLE- 

->/OPTIONS/CODE : PIC FCSRES/OVERLAY_DESCRIPTION 

Option? STACK=0 

Option? PAR=FCSRES: 0: 20000 

Option? GBLREF=. CLOSE 

Option? GBLREF=.CSI1 

Option? GBLREF=.CSI2 



Option? GBLREF=. WAIT 
Option? <RET> 

>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL_TABLE : ■ 
->F4PCLS/TASK:F4PCLS/OPTIONS F4PRES, LB: [1,1]F4P0TS- 
->/LIBRARY, LB: [1,1 ] SYS LIB/INCLUDE : FCSVEC 
Option? STACK=0 

Option? PAR=F4PCLS: 140000: 40000 
Option? GBLINC=.FCSJT 
Option? GBLXCL=. CLOSE 
Option? GBLXCL=.CSI1 
Option? GBLXCL=.CSI2 



Option? GBLXCL=.WAIT 
Option? <RET> 

Referencing task is created using normal procedure to 
reference libraries FCSRES and F4PCLS. 
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Figure F-6 Using Revectoring When Referencing Library Has Overlays 
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CLUSTER LIBRARIES 

• Allow shared libraries to overlay each other (Figure F-7). 

Can use one window for several libraries. 

Only enough virtual address space is needed for 
largest library, 

• One library can call another. 

- Generally moving in one direction only. 

First library in cluster is initially mapped (no 
autoload) . 

When a call is made to another library in cluster: 

Autoload routines save mapping context and map 
called library for a call. 

Original library is remapped for return from 
subroutine. 

• Revectoring is necessary for interlibrary calls (Figure 
F-5). 

Special coding must be included in the resident 
1 ibrar ies . 

• Some special rules must be followed when building the 
resident libraries. 

• Are useful for FORTRAN tasks using the resident object 
time system (FORRES, F4PRES, or F77RES) , plus layered 
products . 

See Section 5.2 on Cluster Libraries in the RSX-11M/M-PLUS 
Task Builder Manual for additional information. 

Example of task-build command: 

>LINK/MAP/OPTIONS/CODE:FPP CLSDEM , LB : [ 1 , 1 ] HLLFOR , - 
->LB: [1, 1]F4P0TS/LB,LB: [1,1] FDVL IB/LB 
Option? CLSTR=F4PCLS, FMSCLS , FCSRES : RO 
Option? <RET> 
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Figure F-7 Cluster Libraries (Sheet 1 of 2) 
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Figure F-7 Cluster Libraries (Sheet 2 of 2) 
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APPENDIX G 
ADDITIONAL EXAMPLES 



The following examples should be available on-line, probably 
under UFD [202,1]. They are needed for the Tests/Exercises. 
Therefore, they are listed here in case they are not available 
on-line at your site. 



6 
7 
8 
9 
10 
1.1. 
12 
13 
.14 
.1.5 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 



TITLE READF 
I DENT /01/ 
ENABL. LC 



9 Enable lower esse 



? File READF ♦ MAC 



This task starts up? sets event flag 1? reads the 
event flams .» moves them into registers R0-R3 and then 
exits* It uses the $ form of the directive calls* 



J The flams are returned as follows* 



b i t 
bit 



set 



word 
word 
word 
word 
means 



~ event 

- event 

- event 
™ event 

flam is 



f lams 

f 3.3J3S 

flams 
flams 
set y 



1-16 
17-32 
33-48 
49-64 



clear means flam is clear 



♦ MCALL RD AF$ y SETF* y EX I T*S y D I R$ ? System macros 



BUFF ♦* 

read: 

SETF t 

start: 



♦ BLKW 
RDAF* 

SETF* 



CLR 
DIR* 
BCS 
DIR* 

MOV 
MOV 
MOV 
MOV 
1 0T 



4 

BUFF 
1 



R4 

#SETF 

ERR1 

♦READ 

ERR 2 
BUFFyRO 
BUFF+2»R1 
BUFF+4 y R2 
BUFF+6*R3 



y Come here on directive errors 



ERR2 1 
ERR1 : 



INC 
INC 

MOM 
I0T 

♦ END 



R4 
R4 

*DSWyR0 



START 



9 Buffer for event flam 
y values 

y DPB for Read All Event 
9 Flams directive 

y DPB for Set Event Flam 
y directive 

y Clear error counter 

5 Set event flam 1 

9 Branch on dir error 

9 Re3d the event flams 
? <1 - 64)* 

y Branch on dir error 

y Move the event flam 

y values into the 
y registers 

y Trap 3nd display 
y registers 



y R4~2 for read error 

y R4=l for set event 

y flam error 

y Error code into R0 

y Trap 3nd display the 

y registers 



Example G-l Reading the Event Flags (for Exercise 1-1) 

537 



3. 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
1(3 
19 
20 
21 

23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 



♦TITLE CSI 
* I DENT /01/ 
♦ ENABL LC 



i Enable lower case 



y CSI illustrates the use of the command string 

y interpreter* This task accepts a command line from the 

y terminal in the form* 

y 

9 d e v ♦ C x 9 « 3 f i .1. e n a m e ♦ f i 1 e t w p e ? v e r s i o n / s w :i. t c h 

9 

i where switch can be* 

9 DE - Delete file 

9 D I ♦ N - D i s p 1 a w N c o p i e s o f f :i. I e 

♦ MCALL GCMLB*yGCML*yCSI*yCSI*l yCSI*2 
♦MCALL CSI*SVyCSI*SWyCSI*ND 

♦ MCALL FSRSZ* r FDBDF* y FDRC*A t FD0P*A 9 FIN IT* 

♦ MCALL QI0W*S 9 QIOW* y DIR* y EXIT*B 

♦ MCALL DELET* 1 0PEN*R y 0PEN*W y GET* y PUT* y CLOSE* 

♦NLIST BEX 



TYPHI : 
TYPE 2 * 
TYPE3 * 
TYPE4 * 
ERR1 ♦ 

ERR2: 

ERR3 J 

ERR4J 

BUFFJ 
TBUFF i 
FMT * 

data: 

deltxt: 

tytxt: 

notxt: 



CBLKJ 



LOCAL DATA 

Q I0W* 1 ♦ W VB y 5 y 1 y y y y <ERR 1 t S I Z 1 y 40> 
Q I OW* 10 ♦ WVB y 5 y 1 y y y y <ERR2 y S 1 22 y 40> 
QIOW* 10. WVB y 5 y 1 y y y y <ERR3 y S I Z3 1 40> 
QIOW* 1 ♦ W VB 9 5 y 1 y y y y <ERR4 y SIZ4 y 40> 
♦ASCII /GET COMMAND LINE ERROR/ 
SIZl™ ♦ "-ERR1 
♦ASCII /CSI 



SIZ2«*-ERR2 
♦ASCII /CSI 
SIZ3=*-ERR3 
♦ASCII /ERROR 
SIZ4=*~ERR4 



ERROR* ILLEGAL COMMAND/ 
ERROR ♦ FILE SPEC ERROR/ 
PERFORMING TASK/ 



♦ BLKB 

♦ BLKB 

♦ ASCIZ 

♦ EVEN 
♦WORD 
♦ASCII 
♦ASCII 
♦ASCII 

♦ EVEN 

CSI* 

♦ BLKB 

♦ EVEN 



100, ? Output text buffer 

132* y Transfer buffer 

/YOU HAVE REQUESTED A %7A JOB/ 



/DELETE/<0> 

/type/<oxoxo: 

/NOTHING/ 



C.SIZE 



A r si u m e n t b 1 o c k 
ASCII text 



y Define CSI offsets 
y allocate CSI storage 



DEMSK 
DIMSK 



- 1 



Delete mask 
Display mask 
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54 SWTBLJ y Switch descriptor table 

55 CSI*SW DEyDEMSK t Delete switch « DE 

56 CS I *S W D I r D I'MSK nn NUM y D i sp 1 ay sw i tch « D I r 

57 ? also allow Dl'JN 

58 CSI*ND i End of switch table 
59 

60 CSI*SV OCTAL y COPY y 2 y NUM y Value N for /DUN is 

61 y in octal and will 

62 y be stored in COPY 

63 CSISND i End of switch value 

64 > table 
65 

66 9 GET COMMAND LINE BLOCK DEFINITIONS 
67 

68 FSRSZ* 1 r GCML uses record I/O 
69 

70 GBL K J G C M L B* a»CSI y y 5 y P r o m p t w i t h ' C S I ' o n 

71 9 LUN 5 

72 FDB: FDBDF* y FDB for file to delete 

73 y or display* 

74 FDRC*A y'TBUFFyl32* ? URB AT TBUFI-y length 

75 y 132* 

76 FD0P*A 1»CBLK+C.DSDS y LUN ly dataset 

77 y descriptor from CSI 
78 

79 9 NOTE I Need a 2nd FDB for display 
80 

81 ♦ EVEN 
82 

83 JMPTBL i ♦ WORD NONE y DELETE y Dl'SPLY y Jump table for 

84 y subroutines depending 

85 y on switches 
86 

87 COPY: ♦ WORD ? Value for N in /DUN 

88 * ENABLE LSB 
89 

90 START? FIN IT* y Initialize FCSy this 

9.1 9 is normally done with 

92 y an OPEN statement* 

93 y For delete we do not 

94 y need an open statement* 

95 NEXT: GCML* #GBLK y Prompt and get command 

96 BCC .10* y Branch if command OK 

97 9 Check for "Z* If ~Zy exit* 

98 CMPB #GE ♦ EOF y GBLKf G ♦ ERR y Is it "Z? 

99 BNE REALER 5 Branch on other error 

100 EXIT*S ? Exit 

101 REALER : DIR* #TYPEi y Display error text for 

1 02 J =iet co m m a n d 1 i n e e r r o r 

103 EXIT*S y Exit 
104 

105 y Parse input for illegal characters 
106 

107 10*: CSI*1 ttCBLK'y GBLKf G * CMLD+2 y GBLK-f G * CMLD y Format 

108 9 is CSI addr9 sddr of 

109 y command.* length of 

110 y command 



Example G-2 Using the Routines GCML and CSI (for Exercise 10-6) 

(Sheet 2 of 3) 



539 



■ill BCC 20* r Branch on OK command 

112 DIR* #TYPE2 9 Display error text for 

113 9 illegal command 

114 EXIT*S 9 Exit 
.1. 1 5 

116 9 Create a dataset descriptor from the file specification 
1 1 7 

118 20$J CSI*2 #CBLKy OUTPUT y#SWTBL 9 Expect output file 

119 9 spec 

120 BCC 30$ 9 Branch on file spec OK 

121 DIR* #TYPE3 9 Display text for file 
.1.22 9 spec error 

123 EX.TT*S 9 Exit 
124 

125 9 Call the appropriate subroutine 
126 

127 30* i MOV #FDB » R0 9 Address of file 

128 ? descriptor 

129 MOV CBLK'f C ♦ MKWl y Rl 9 Mask value « O9 lr or 2 

130 ASL Rl 9 Double for word offset 

131 9 into Jump table 

132 CALL ejMPTBL(Rl) 9 Call the subroutine 

133 BR NEXT f Get next command line 
134 

135 ? Subroutine NONE y entered if no switches specified 
136 

137 NONE * MOV #N0TXT y DATA 9 Set up for output of 

138 y message 
139 

140 y Common display message code 
141 

142 OUTMi MOV ♦BUFF 9 R0 9 Set up for *EDMSG 

.1.43 MOV #FMTyR.1. 9 

144 MOV #DA')'A y R2 9 

145 CALL * ED MSG ? Edit message 

146 Q 1 W * S # 1 . W V B y # 5 :•• * If ft 9 < # B U F F t R .1. r * 4 > 9 D i s p 1 a y 

147 RETURN 9 Return 



148 

149 9 Subroutine DELETE •••• Just display a message 
150 

151 DELETE: MOV # DEL TXT y DATA 9 Set up for output of 



152 9 message 

153 BR 0UTM y Branch to common 
.1.54 5 display code 
155 



156 9 Subroutine DISPLY - Just display a message 
157 

158 DISPLY? MOV # TYTXT y DATA 9 Set up for output of 



159 9 message 

160 BR 0UTM y Branch to common 

161 9 display code 

162 ♦ END START 
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APPENDIX H 

LEARNING ACTIVITY ANSWER SHEET 



Learning Activity 2-1 (Directives) 

1. Either: a) Do some work, then check the flag by using the 
CLEF$ 35. directive. Check the DSW. IS. SET (=+2) means 
the flag was set; IS.CLR (=0) means the flag was clear, 
or b) read flags 4 through 64 using RDAF$ and then test 
bit 2 of the third word in the buffer to read flag 35. In 
either case, keep doing more specific work and 
periodically check the flag. 

2. The Executive, would only set event flag 1 for Task A. It 
would not set Task B's event flag 1; therefore, Task B 
wouldn't realize that the data had been sent. 

3. Local flags are accessible only to the task itself. They 
are specifically provided for synchronization between the 
Executive and a task. 
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Learning Activity 6-1 (Overlays) 



l. 



.ROOT-*! (P,Q) 
.END 



2. LINK/MAP ROOT, P, Q 



Learning Activity 6-2 

1. Diagram 

JOB1 JOBXX 



TOTAL 
I 

MAIN 



2. .ROOT MAIN-TOTAL-* (A- (JOB1, JOBXX) ,B) 
.END 

3. .ROOT MAIN-TOTAL-*! (A-« (JOB1, JOBXX) ,B) 
. END 

4. .ROOT MAIN-TOTAL-*! (A- (JOB1, JOBXX) ,B) 
.END 
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Learning Activity 10-1 (File Control Services) 



Without a User Record buffer (no spanning of blocks) : 



FDBDF$ 
FDRC$A 
FD0P$A 
DFNB: NMBLK$ 



FD.PLC 
1 , DFNB 
YOURS , MAC 



Use locate mode 

Use LUN 1, default name block 

File Spec 



With a User Record Buffer 



FDBDF$ 

FDRC $A FD . PLC , URB ,80. 



FD0P$A 1 , DFNB 
DFNB: NMBLK$ YOURS. MAC 



80.= maximum record size, 
Record size can be checked after 
the file is opened as well. 



You can use a dataset descriptor as well. 
If you use a default name block to specify TI:, use: 
NMBLK$ ,,,TI,0 
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GLOSSARY 



ASYNCHRONOUS SYSTEM TRAP (AST) - A system condition which occurs 
as a resul t of a speci f ied event such as completion of an I/O 
request . 

On occurrence of the event, control passes to an AST service 
routine, and the AST is added to an Executive first-in first-out 
queue for the task in which the service routine appears. 

ATTACH - Device: Dedicate a physical device unit for exclusive 
use by the task that requested attachment. 

A task attaches a given device by issuing a QIO directive, or QIO 
and WAIT directive, specifying the I/O function 10. ATT. 

Region: Include a region in a task's logical address space. 

A task attaches a region by issuing an Attach Region directive or 
by being the target of another task's Send-By-Ref erence directive. 

CLUSTER LIBRARIES - A special setup with shared resident libraries 
which permits a task to use the same virtual address window to map 
several difficult libraries. For example, the resident FORTRAN 
Object Time System and the resident FCS library could use the same 
virtual addresses. The run-time routines map and remap the 
regions as they are needed, somewhat similar to what happens with 
regular memory-resident overlays. 

DATASET DESCRIPTOR - A six-word area in the user task containing 
sizes and addresses of ASCII data strings, which FCS consults in 
order to obtain a run-time file specification. 

A dataset descriptor for a given file is a user-created data 
structure which contains a file specification for that file. 

When the filename block associated with a given file does not 
contain sufficient information to enable FCS to do run-time file 
processing on that file, FCS tries to get the needed information 
from the file's dataset descriptor, if specified. Otherwise, FCS 
consults the file's default filename block, if specified, in order 
to get the desired information. 

DEFAULT FILENAME BLOCK - An area in the user task that supplies 
FCS with those default values that are needed to build a routine 
file specification. 

When the filename block associated with a given file does not 
contain sufficient information to allow FCS to process the file, 
and when a dataset descriptor does not contain the needed 
information, then FCS consults the default filename block 
associated with the file to obtain the missing information. 
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A default filename block may be used to supply a default name, 
extension, and/or version for the file. The MACRO programmer uses 
the NMBLK$ macro to create this block at assembly time. 

DETACH - Device: Free an attached physical device unit for use by 
tasks other than the one that attached it. 

A physical device unit can only be detached by means of an IO.DET 
I/O function issued by the task that attached it, or by the 
Executive, if the task is terminated with the device still 
attached . 

Region: Remove a region from a task's logical address space. 

A task detaches a region by issuing a Detach Region directive or 
by ex i ting . 

DIRECTIVE STATUS WORD - A word in the user task header into which 
the Executive returns status information about the most recently 
called directive. 

After processing a directive, the Executive passes the status of 
that directive to the issuing task by putting a success or error 
code into the task's Directive Status Word, which is assigned the 
global label $DSW. If $DSW is negative, the Executive rejected 
the directive; if $DSW is +1, the directive was successful. 

EVENT FLAG - A software flag which can be specified in a program 
request to indicate to the issuing task which of several specified 
events has occurred. 

There are 96(10) event flags. 

Event flags 1 - 32(10) are local 

33(10) - 64(10) are system global flags 
65 (10) - 96 (10) are group global flags 

Local flags are used for intra-task synchronization, while group 
global and system global flags are used for inter-task 
synchronization and communication. 

EXECUTIVE DIRECTIVE - A program request for Executive services. 

An Executive directive is issued from a FORTRAN program by calling 
a subroutine in the system object library. It is issued from a 
MACRO-11 program by invoking a macro in the system macro library. 

FILE DESCRIPTOR BLOCK (FDB) - The tabular data structure which 
provides FCS with information needed to perform I/O operations on 
a file. 
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A task must allocate, through calls to the FDBDF$ macro, or 
dynamically through the use of run-time macros. 

FILE STORAGE REGION (FSR) - The area in user task which FCS uses 
to buffer all virtual blocks read or written during record 
processing . 

FCS requires one FSR block buffer for each file to be opened at 
the same time for record I/O. When the task requests a record 
that is not in the FSR buffer, FCS reads a virtual block from the 
file into the task's file storage region. On the other hand, FCS 
writes virtual blocks in the file storage region to the file when 
a record must be put to the file. 

The user task allocates this area by issuing an FSRSZ$ macro. 

FILENAME BLOCK - The part of a file's File Descriptor Block which 
FCS uses for building, and later using, a file specification. 

The filename block contains the file's UFD, name, extension, 
version number, device name, and unit. When a file is initially 
opened, FCS fills in the filename block from user-supplied 
information in the dataset descriptor and/or default filename 
block. 

I/O STATUS BLOCK - A two-integer array which receives success or 
error codes on completion of an I/O request. If an I/O status 
block has been specified in an I/O request, the Executive clears 
both words when the I/O operation is queued. On completion, the 
low byte of the first word contains +1 if the I/O was successful, 
and a negative error code otherwise. 

If the I/O function involved a transfer, the second word contains, 
on completion, the number of bytes transferred. 

LOGICAL ADDRESS SPACE - The set of all physical addresses to which 
a task has access rights. 

If a task is running on a mapped system that includes support for 
the memory management directives, it may issue directives in order 
to manipulate its logical address space at run time. 

LOGICAL BLOCK - A 512(10) byte (256(10) word) block of data on a 
block addressable volume. 

To achieve device independence, each block addressable volume is 
organized into logical blocks, numbered to n-1, where n is the 
number of logical blocks on the volume. 

The mapping of logical blocks to physical blocks is handled by the 
driver. 
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LOGICAL UNIT NUMBER ( L UN ) - A number associated with a physical 
device unit during a task's I/O operations. 

The association of a LUN in a task with a given physical device 
may be done by the Task Builder, by the operator using the 
REASSIGN command, or at run time by the task, by issuing an Assign 
LUN directive. 

RANDOM ACCESS - A method of I/O to disk files in which records (or 
virtual blocks) are specified by record (or virtual block) number. 

Under FCS, a file must be organized into fixed length records in 
order for a task to do random access to the file. 

FCS supports the use of block I/O, in which virtual blocks are 
read from, or written to, the file without regard for the 
structure of those blocks. The FORTRAN language does not support 
block I/O. 

READ/WRITE MODE - An FCS file access method in which the user task 
uses the READ$ and WRITE$ macros to do block-structured I/O to a 
file. 

REGION - An area consisting of one or more contiguous 32. -word 
blocks of physical memory. 

A region may be named or unnamed, but is always assigned a unique 
region ID. A region has an associated protection word which 
specifies the access rights a task may have with respect to that 
region. Any task that satisfies the region protection word may 
attach a named region, but no task can attach an unnamed region 
unless the task has the region ID. 

RESIDENT COMMON - A shared region which contains data. 

RESIDENT LIB-RARY - A shared region containing subroutines and/or 
functions . 

SEQUENTIAL ACCESS - A mode of record access in which the n+lth 

record in the file is processed after the nth record in the file. 

Each record is assigned a record number, and each successive GET 
or PUT causes the record number to be incremented. 

SYNCHRONOUS SYSTEM TRAP (SST) - A "software interrupt" which 
typically occurs as a result of an error or fault within the 
executing task. 

On recognition of an SST, the Executive aborts the task, unless 
there is an SST vector table to an SST routine in the task. 
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VIRTUAL ADDRESS - A 16-bit address which may be directly specified 
using one ot the general purpose registers. 

A task specifies a virtual address whenever it uses one of the 
addressing modes in executing an instruction. Up to 32K virtual 
word addresses may be specified by a task. 

On a mapped system, the memory management hardware dynamically 
maps virtual addresses to real physical addresses. 

VIRTUAL ADDRESS WINDOW - A contiguous chunk of a task's virtual 
address space. 

Each virtual address window in a task begins on a 4K word boundary 
and consists of one or more 32(10) word blocks of virtual address 
space. Each window has a unique number assigned to it by the 
Executive. Window always maps the task's header, stack, and 
code. A task may divide its virtual address space into eight 
windows . 

VIRTUAL BLOCK - One of the logical blocks belonging to a file. 

Each file consists of one or more logical blocks. The logical 
blocks belonging to a file are called virtual blocks 1, 2, 3, etc. 
The mapping of virtual blocks in a file to logical blocks on disk 
is performed by the file system. 

WINDOW DESCRIPTOR BLOCK (WDB) - A data structure used in a task in 
order to represent a dynamically created window. 
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